@askthew/mcp-plugin 0.4.0 → 0.4.2

package/dist/lib/telemetry.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import { resolvePluginScope } from "../scope.js";
 import { isTelemetryOptedOut } from "./free-tier-policy.js";
+import { tryRegisterFreeInstall } from "./free-install-registration.js";
+import { signLocalIdentityPayload } from "./local-identity.js";
 export function buildTelemetryPayload(input) {
     const now = input.now ?? new Date();
     const sessionId = input.sessionId ?? input.store.mostRecentSessionId() ?? "unknown";
@@ -29,6 +31,13 @@ export function buildTelemetryPayload(input) {
             platform: `${process.platform}-${process.arch}`,
             node: process.version.replace(/^v/, ""),
         },
+        identity: input.credentials.identityKind === "local_install"
+            ? {
+                kind: "local_install",
+                installId: input.credentials.installId,
+                emailClaimed: Boolean(input.credentials.email),
+            }
+            : { kind: "legacy_token" },
     });
 }
 export async function flushTelemetryOutbox(input) {
@@ -37,15 +46,32 @@ export async function flushTelemetryOutbox(input) {
     }
     const fetcher = input.fetchImpl ?? fetch;
     const apiUrl = (input.apiUrl ?? input.credentials.apiUrl ?? process.env.ASKTHEW_API_URL ?? "https://app.askthew.com").replace(/\/$/, "");
+    if (input.credentials.identityKind === "local_install" && input.credentials.localIdentity) {
+        await tryRegisterFreeInstall({
+            identity: input.credentials.localIdentity,
+            deviceLabel: "askthew-mcp",
+            options: { apiUrl, fetchImpl: fetcher },
+        });
+    }
     let sent = 0;
     for (const row of input.store.listTelemetryOutbox({ undeliveredOnly: true, limit: 20 })) {
+        const body = JSON.stringify(row.payload);
+        const signed = input.credentials.identityKind === "local_install" && input.credentials.localIdentity
+            ? signLocalIdentityPayload({ identity: input.credentials.localIdentity, body })
+            : null;
         const response = await fetcher(`${apiUrl}/api/cli/v1/telemetry`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${input.credentials.cliToken}`,
+                ...(signed
+                    ? {
+                        "X-AskTheW-Install-Id": input.credentials.localIdentity.installId,
+                        "X-AskTheW-Timestamp": signed.timestamp,
+                        "X-AskTheW-Signature": signed.signature,
+                    }
+                    : { Authorization: `Bearer ${input.credentials.cliToken}` }),
             },
-            body: JSON.stringify(row.payload),
+            body,
         }).catch(() => null);
         const delivered = Boolean(response?.ok);
         input.store.markTelemetryAttempt(row.id, delivered);

package/dist/lib/timeline-insights.d.ts

@@ -0,0 +1,23 @@
+import type { LocalDecision, LocalSignal } from "./local-store.js";
+export interface TimelinePoint {
+    x: string;
+    signalCount: number;
+    decisionCount: number;
+    startedAt?: string;
+    endedAt?: string;
+    durationMinutes?: number;
+}
+export interface TimelineInsight {
+    id: string;
+    type: "trend" | "recommendation";
+    title: string;
+    body: string;
+}
+export declare function buildLocalTimeline(input: {
+    scope: "day" | "month" | "session";
+    signals: LocalSignal[];
+    decisions: LocalDecision[];
+    limit?: number;
+}): TimelinePoint[];
+export declare function buildTimelineInsights(points: TimelinePoint[]): TimelineInsight[];
+export declare function renderTimelineMarkdown(points: TimelinePoint[], scope: "day" | "month" | "session"): string;

package/dist/lib/timeline-insights.js

@@ -0,0 +1,115 @@
+export function buildLocalTimeline(input) {
+    if (input.scope === "session")
+        return buildSessionTimeline(input);
+    const buckets = new Map();
+    for (const signal of input.signals) {
+        const x = input.scope === "month" ? signal.capturedAt.slice(0, 7) : signal.capturedAt.slice(0, 10);
+        const point = buckets.get(x) ?? { x, signalCount: 0, decisionCount: 0 };
+        point.signalCount += 1;
+        buckets.set(x, point);
+    }
+    for (const decision of input.decisions) {
+        const x = input.scope === "month" ? decision.createdAt.slice(0, 7) : decision.createdAt.slice(0, 10);
+        const point = buckets.get(x) ?? { x, signalCount: 0, decisionCount: 0 };
+        point.decisionCount += 1;
+        buckets.set(x, point);
+    }
+    return [...buckets.values()].sort((left, right) => left.x.localeCompare(right.x));
+}
+export function buildTimelineInsights(points) {
+    const totalSignals = points.reduce((sum, point) => sum + point.signalCount, 0);
+    const totalDecisions = points.reduce((sum, point) => sum + point.decisionCount, 0);
+    const insights = [
+        {
+            id: "timeline.activity_summary",
+            type: "trend",
+            title: "Timeline activity summarized",
+            body: `This period includes ${totalSignals} signals and ${totalDecisions} decisions.`,
+        },
+    ];
+    if (totalSignals >= 20 && (totalDecisions === 0 || totalSignals / Math.max(1, totalDecisions) >= 8)) {
+        insights.push({
+            id: "timeline.signal_to_decision_imbalance",
+            type: "recommendation",
+            title: "Signals are far ahead of decisions",
+            body: `${totalSignals} signals produced ${totalDecisions} decisions. Promote the strongest evidence into decisions before the trail gets noisy.`,
+        });
+    }
+    else {
+        insights.push({
+            id: "timeline.review_next_bucket",
+            type: "recommendation",
+            title: "Review the next decision bucket",
+            body: totalDecisions > 0
+                ? "Open the busiest bucket and check whether the decisions still describe the current plan."
+                : "Capture one decision for the most important change before the next review.",
+        });
+    }
+    const maxDecision = Math.max(0, ...points.map((point) => point.decisionCount));
+    const averageDecision = points.reduce((sum, point) => sum + point.decisionCount, 0) / Math.max(1, points.length);
+    if (maxDecision >= 4 && maxDecision >= averageDecision * 2.5) {
+        insights.push({
+            id: "timeline.decision_spike",
+            type: "trend",
+            title: "Decision spike detected",
+            body: `One bucket captured ${maxDecision} decisions, well above the period average of ${averageDecision.toFixed(1)}.`,
+        });
+    }
+    return insights.slice(0, 6);
+}
+export function renderTimelineMarkdown(points, scope) {
+    const label = scope === "session" ? "Session" : scope === "month" ? "Month" : "Date";
+    return [`| ${label} | Signals | Decisions |`, "|---|---:|---:|", ...points.map((point) => `| ${point.x} | ${point.signalCount} | ${point.decisionCount} |`)].join("\n");
+}
+function buildSessionTimeline(input) {
+    const sessions = new Map();
+    for (const signal of input.signals) {
+        const existing = sessions.get(signal.sessionId) ?? {
+            x: signal.sessionId,
+            signalCount: 0,
+            decisionCount: 0,
+            startedAt: signal.capturedAt,
+            endedAt: signal.capturedAt,
+            durationMinutes: 0,
+        };
+        existing.signalCount += 1;
+        existing.startedAt = minIso(existing.startedAt, signal.capturedAt);
+        existing.endedAt = maxIso(existing.endedAt, signal.capturedAt);
+        existing.durationMinutes = durationMinutes(existing.startedAt, existing.endedAt);
+        sessions.set(signal.sessionId, existing);
+    }
+    for (const decision of input.decisions) {
+        const sessionId = decision.sessionId;
+        if (!sessionId) {
+            continue;
+        }
+        const existing = sessions.get(sessionId) ?? {
+            x: sessionId,
+            signalCount: 0,
+            decisionCount: 0,
+            startedAt: decision.createdAt,
+            endedAt: decision.createdAt,
+            durationMinutes: 0,
+        };
+        existing.decisionCount += 1;
+        sessions.set(sessionId, existing);
+    }
+    return [...sessions.values()]
+        .sort((left, right) => String(right.endedAt ?? "").localeCompare(String(left.endedAt ?? "")))
+        .slice(0, input.limit ?? 50);
+}
+function minIso(left, right) {
+    if (!left)
+        return right;
+    return left <= right ? left : right;
+}
+function maxIso(left, right) {
+    if (!left)
+        return right;
+    return left >= right ? left : right;
+}
+function durationMinutes(start, end) {
+    if (!start || !end)
+        return 0;
+    return Math.max(0, Math.round((new Date(end).getTime() - new Date(start).getTime()) / 60000));
+}

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

@@ -1,6 +1,6 @@
 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 paidDescription(description: string, mode: "paid" | "free" | "free_pending_auth" | "unauthenticated"): string;
 export declare function paidFeatureNudge(tool: string): {
     ok: boolean;
     code: string;

package/dist/lib/upgrade-nudge.js

@@ -7,11 +7,18 @@ export function paidDescription(description, mode) {
     return `${description} (paid - ${PRICING_URL})`;
 }
 export function paidFeatureNudge(tool) {
+    const feature = tool.includes("outcome")
+        ? { label: "Outcomes", verb: "are" }
+        : tool.includes("north_star")
+            ? { label: "North star", verb: "is" }
+            : tool.includes("export")
+                ? { label: "Exports", verb: "are" }
+                : { label: "This workspace feature", verb: "is" };
     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.",
+        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)}`,
         supportEmail: SUPPORT_EMAIL,

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

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

package/dist/local-identity.test.js

@@ -0,0 +1,29 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ensureLocalIdentity, signLocalIdentityPayload } from "./lib/local-identity.js";
+import { identityPath } from "./lib/paths.js";
+test("local identity uses install id as primary identity and signs summary payloads", () => {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-local-identity-"));
+    try {
+        const env = { ASKTHEW_DATA_DIR: dataDir };
+        const identity = ensureLocalIdentity({
+            emailClaim: "Founder@Example.com",
+            apiUrl: "https://app.askthew.com",
+            env,
+        });
+        const body = JSON.stringify({ schemaVersion: 1, activity: { signalCount: 1 } });
+        const signed = signLocalIdentityPayload({ identity, body, timestamp: "2026-05-07T12:00:00.000Z" });
+        assert.match(identity.installId, /^[0-9a-f-]{36}$/);
+        assert.equal(identity.emailClaim, "founder@example.com");
+        assert.equal(fs.existsSync(identityPath(env)), true);
+        assert.equal(crypto.verify(null, Buffer.from(`${signed.timestamp}.${body}`), identity.publicKey, Buffer.from(signed.signature, "base64url")), true);
+        assert.equal(crypto.verify(null, Buffer.from(`${signed.timestamp}.${JSON.stringify({ tampered: true })}`), identity.publicKey, Buffer.from(signed.signature, "base64url")), false);
+    }
+    finally {
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+});

package/dist/local-store.test.js

@@ -35,3 +35,37 @@ test("local store migrates, captures signals, decisions, and FIFO telemetry", ()
     store.close();
     fs.rmSync(dir, { recursive: true, force: true });
 });
+test("local store scopes trail rows, links decisions, and tracks lifecycle timestamps", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-store-scope-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    const scoped = store.insertSignal({
+        sessionId: "s1",
+        sequence: 1,
+        kind: "direction_change",
+        summary: "Let's go with local search because it is fast.",
+        scopeKey: "repo-a",
+    });
+    store.insertSignal({
+        sessionId: "s2",
+        sequence: 1,
+        kind: "direction_change",
+        summary: "Use a different decision in another repo.",
+        scopeKey: "repo-b",
+    });
+    const decision = store.createDecision({
+        rawContent: "Adopt local search.",
+        sessionId: "s1",
+        sourceSignalIds: [scoped.id],
+        scopeKey: "repo-a",
+    });
+    const committed = store.updateDecision(decision.id, { status: "committed" });
+    assert.equal(store.listSignals({ scopeKey: "repo-a" }).length, 1);
+    assert.equal(store.listSignals({ scopeKey: "repo-b" }).length, 1);
+    assert.equal(store.listDecisions({ scopeKey: "repo-a" }).length, 1);
+    assert.equal(store.getDecisionForSignal(scoped.id)?.id, decision.id);
+    assert.equal(Boolean(decision.proposedAt), true);
+    assert.equal(Boolean(committed?.committedAt), true);
+    assert.equal(store.mostRecentSessionId({ scopeKey: "repo-a" }), "s1");
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+});

package/dist/scope.d.ts

@@ -4,4 +4,4 @@ export interface PluginScope {
     appPath?: string;
     serviceName?: string;
 }
-export declare function resolvePluginScope(startDirectory?: string): PluginScope;
+export declare function resolvePluginScope(startDirectory?: string, env?: NodeJS.ProcessEnv): PluginScope;

package/dist/scope.js

@@ -1,6 +1,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 const REPO_MARKERS = [".git", "package.json", "pyproject.toml", "go.mod", "Cargo.toml"];
+const PROJECT_ROOT_ENV_KEYS = [
+    "ASKTHEW_REPO_ROOT",
+    "ASKTHEW_PROJECT_ROOT",
+    "CODEX_WORKSPACE",
+    "CODEX_PROJECT_DIR",
+    "CLAUDE_PROJECT_DIR",
+    "MCP_PROJECT_ROOT",
+    "PROJECT_ROOT",
+    "WORKSPACE_FOLDER",
+    "GITHUB_WORKSPACE",
+    "INIT_CWD",
+    "PWD",
+];
 function parseAskTheWToml(filePath) {
     if (!fs.existsSync(filePath)) {
         return {};
@@ -35,10 +48,51 @@ function findRepoRoot(startDirectory) {
     }
     return highestMarkerDirectory;
 }
-export function resolvePluginScope(startDirectory = process.cwd()) {
+function cleanEnv(value) {
+    return String(value ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
+}
+function explicitEnvScope(env) {
+    const repoName = cleanEnv(env.ASKTHEW_REPO_NAME);
+    const repoRoot = cleanEnv(env.ASKTHEW_REPO_ROOT);
+    const appPath = cleanEnv(env.ASKTHEW_APP_PATH);
+    const serviceName = cleanEnv(env.ASKTHEW_SERVICE_NAME);
+    if (!repoName && !repoRoot) {
+        return null;
+    }
+    const resolvedRoot = repoRoot ? path.resolve(repoRoot) : undefined;
+    return {
+        repoName: repoName || path.basename(resolvedRoot ?? process.cwd()),
+        ...(resolvedRoot ? { repoRoot: resolvedRoot } : {}),
+        ...(appPath ? { appPath } : {}),
+        ...(serviceName ? { serviceName } : {}),
+    };
+}
+function envRepoRoot(env) {
+    for (const key of PROJECT_ROOT_ENV_KEYS) {
+        const value = cleanEnv(env[key]);
+        if (!value)
+            continue;
+        const candidate = findRepoRoot(value);
+        if (candidate)
+            return candidate;
+    }
+    return null;
+}
+export function resolvePluginScope(startDirectory = process.cwd(), env = process.env) {
     const cwd = path.resolve(startDirectory);
+    const envScope = explicitEnvScope(env);
+    if (envScope) {
+        return envScope;
+    }
     const parsedConfig = parseAskTheWToml(path.join(cwd, ".asktheworld.toml"));
-    const repoRoot = parsedConfig.repoRoot || findRepoRoot(cwd) || cwd;
+    const discoveredRoot = findRepoRoot(cwd);
+    const fallbackEnvRoot = envRepoRoot(env);
+    const repoRoot = parsedConfig.repoRoot ||
+        (fallbackEnvRoot && (!discoveredRoot || path.basename(discoveredRoot) === "task")
+            ? fallbackEnvRoot
+            : discoveredRoot) ||
+        fallbackEnvRoot ||
+        cwd;
     const repoName = parsedConfig.repoName || path.basename(repoRoot);
     const relativePath = path.relative(repoRoot, cwd);
     const normalizedRelativePath = relativePath && relativePath !== "." && !relativePath.startsWith("..")

package/dist/scope.test.js

@@ -30,3 +30,20 @@ test("resolvePluginScope respects explicit .asktheworld.toml values", () => {
     assert.equal(scope.serviceName, "decisions");
     fs.rmSync(tempRoot, { recursive: true, force: true });
 });
+test("resolvePluginScope prefers install-time repo env over npx sandbox cwd", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-scope-env-"));
+    const repoRoot = path.join(tempRoot, "ThesisEngine-main");
+    const sandboxRoot = path.join(tempRoot, "task");
+    fs.mkdirSync(path.join(repoRoot, ".git"), { recursive: true });
+    fs.mkdirSync(sandboxRoot, { recursive: true });
+    fs.writeFileSync(path.join(sandboxRoot, "package.json"), "{}", "utf8");
+    const scope = resolvePluginScope(sandboxRoot, {
+        ASKTHEW_REPO_NAME: "ThesisEngine-main",
+        ASKTHEW_REPO_ROOT: repoRoot,
+        ASKTHEW_APP_PATH: "apps/app",
+    });
+    assert.equal(scope.repoName, "ThesisEngine-main");
+    assert.equal(scope.repoRoot, repoRoot);
+    assert.equal(scope.appPath, "apps/app");
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});

package/dist/timeline-insights.test.d.ts

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

package/dist/timeline-insights.test.js

@@ -0,0 +1,85 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildTimelineInsights, buildLocalTimeline } from "./lib/timeline-insights.js";
+function signal(id, day) {
+    return {
+        id,
+        sessionId: "session-a",
+        sequence: id,
+        kind: "session_checkpoint",
+        summary: "checkpoint",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [],
+        metadata: {},
+        capturedAt: `${day}T10:00:00.000Z`,
+    };
+}
+test("local timeline buckets signals and decisions by day", () => {
+    const decisions = [{
+            id: "d1",
+            sessionId: "session-a",
+            headline: "Decision",
+            why: null,
+            status: "proposed",
+            alignment: null,
+            files: [],
+            sourceSignalIds: [],
+            rawContent: "Decision",
+            createdAt: "2026-05-01T11:00:00.000Z",
+            updatedAt: "2026-05-01T11:00:00.000Z",
+            uploadedAt: null,
+        }];
+    const points = buildLocalTimeline({
+        scope: "day",
+        signals: [signal(1, "2026-05-01"), signal(2, "2026-05-02")],
+        decisions,
+    });
+    assert.deepEqual(points.map((point) => [point.x, point.signalCount, point.decisionCount]), [
+        ["2026-05-01", 1, 1],
+        ["2026-05-02", 1, 0],
+    ]);
+});
+test("local timeline insight ids stay in timeline namespace", () => {
+    const insights = buildTimelineInsights([{ x: "2026-05-01", signalCount: 20, decisionCount: 1 }]);
+    assert.ok(insights.every((insight) => insight.id.startsWith("timeline.")));
+});
+test("session timeline buckets by sessionId without inventing Other", () => {
+    const decisions = [
+        {
+            id: "d1",
+            sessionId: null,
+            headline: "Decision without session",
+            why: null,
+            status: "proposed",
+            alignment: null,
+            files: [],
+            sourceSignalIds: [],
+            rawContent: "Decision without session",
+            createdAt: "2026-05-01T11:00:00.000Z",
+            updatedAt: "2026-05-01T11:00:00.000Z",
+            uploadedAt: null,
+        },
+        {
+            id: "d2",
+            sessionId: "session-a",
+            headline: "Decision with session",
+            why: null,
+            status: "proposed",
+            alignment: null,
+            files: [],
+            sourceSignalIds: [],
+            rawContent: "Decision with session",
+            createdAt: "2026-05-01T11:00:00.000Z",
+            updatedAt: "2026-05-01T11:00:00.000Z",
+            uploadedAt: null,
+        },
+    ];
+    const points = buildLocalTimeline({
+        scope: "session",
+        signals: [signal(1, "2026-05-01")],
+        decisions,
+    });
+    assert.deepEqual(points.map((point) => point.x), ["session-a"]);
+    assert.equal(points[0]?.decisionCount, 1);
+});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
-  "description": "Ask The W MCP connector for local-first coding-agent decisions, signals, and review.",
+  "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",