@askthew/mcp-plugin 0.4.0 → 0.4.3

package/README.md

@@ -1,21 +1,20 @@
-# Ask The W MCP Plugin
+# Ask The W Plugin
 
 Connect a local coding agent to Ask The W. The fastest path is free and local-first:
 
 ```bash
-npx -y --prefer-online @askthew/mcp-plugin@latest install --host claude_code --free
-npx @askthew/mcp-plugin auth login --email you@founder.com
+npx -y --prefer-online @askthew/mcp-plugin@latest install --host claude_code --free --email you@founder.com
 ```
 
-This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent run `review_decisions`, `review_session`, and `analyze_session` without onboarding into the web app.
+This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent run `review_decisions`, `review_session`, `recap`, `coach`, and `promote_signal_to_decision` without onboarding into the web app.
 
-Founder-friendly promise: install from npm, magic-link login, then ask your coding agent to review the last session. You should see value in under 60 seconds.
+Founder-friendly promise: install from npm, then ask your coding agent to review the last session. You should see value in under 60 seconds.
 
 This package runs a small MCP server that lets Codex, Claude Code, Cursor, and other MCP-capable tools send compact work-session signals to an Ask The W workspace.
 
 ## What It Does
 
-- Installs an Ask The W MCP server entry into a supported local client.
+- Installs an Ask The W plugin server entry into a supported local client.
 - Preserves existing MCP servers and settings.
 - Adds marked project instructions so future coding-agent sessions know when to send Ask The W updates.
 - Free mode stores full-fidelity signals and decisions locally in SQLite.
@@ -38,12 +37,13 @@ Ask The W performs inference, linking, approval state, dedupe, and outcome updat
 ```bash
 npx -y --prefer-online @askthew/mcp-plugin@latest install \
   --host claude_code \
-  --free
-
-npx @askthew/mcp-plugin auth login --email you@founder.com
+  --free \
+  --email you@founder.com
 ```
 
-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. We do tie aggregate counts, stack, and tool usage to your email for upgrade onboarding. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
+Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP config and agent instructions immediately, and never requires an email code before local capture works. The email is an unverified claim used for upgrade onboarding only; data is keyed by the generated install ID, not email alone.
+
+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`.
 
 ## Workspace Install
 
@@ -85,7 +85,7 @@ After install, restart or reload your coding agent if needed. At the start of ev
 
 Claude Desktop and Cowork custom connectors use Ask The W's hosted Remote MCP URL instead of this local `npx` installer. In Ask The W, create a Claude Remote URL from the plugin source, then paste it into Claude's custom connector form as the Remote MCP server URL. The URL must be public HTTPS; `localhost`, `127.0.0.1`, LAN IPs, VPN-only hosts, and firewall-blocked servers will fail because Claude connects from Anthropic's cloud. Treat the URL like a password and rotate it if it leaks.
 
-The installer also adds safe, marked project instructions:
+The installer also adds safe, marked project instructions to both markdown convention files plus any host-specific rule file:
 
 - Codex: `AGENTS.md`
 - Claude Code: `CLAUDE.md`
@@ -155,22 +155,33 @@ The session-signal tool remains the main automatic capture path.
     "evidence": [{ "role": "user | assistant | system", "excerpt": "string" }],
     "filesTouched": ["string"],
     "commandsRun": ["string"],
-    "metadata": {}
+    "metadata": {},
+    "echo": "summary | full"
   }
 }
 ```
 
-Use compact summaries and short evidence excerpts. Do not send full transcripts.
+Use compact summaries and short evidence excerpts. Do not send full transcripts. By default, write tools return compact responses; use `echo: "full"` only when you need the larger payload for debugging.
 
 The plugin also exposes v1 API tools that map to the app's authenticated routes:
 
 | Tool | Purpose |
 |---|---|
 | `list_decisions`, `get_decision`, `create_decision`, `update_decision`, `delete_decision` | Work with decision feed entries. |
+| `review_session`, `recap`, `coach`, `promote_signal_to_decision`, `find_signal_by_summary` | Review local sessions, get session coaching, find recent evidence, and turn signals into decisions in free mode. |
 | `list_outcomes`, `get_outcome`, `list_outcome_signals`, `create_outcome`, `update_outcome`, `delete_outcome` | Work with outcomes and their linked signals. |
 | `get_north_star`, `update_north_star` | Read or update the workspace north star. API updates are allowed only for private workspaces. |
 | `list_signals`, `get_signal` | Read workspace signals. |
 
+Free PLG helpers:
+
+```bash
+npx @askthew/mcp-plugin install-hook --pre-commit
+npx @askthew/mcp-plugin digest --weekly
+```
+
+The hook prompts when staged files recently had implementation signals but no linked decision. The weekly digest writes `~/Documents/askthew-digest-YYYY-WW.md`.
+
 API mutations are text-only and are recorded back into the workspace signal feed. Decision and outcome deletes require a `confirmText` value that exactly matches the stored decision headline or outcome name after whitespace normalization. North star delete is not available through the API.
 
 ## Troubleshooting

package/dist/auth-pending.test.d.ts

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

package/dist/auth-pending.test.js

@@ -0,0 +1,56 @@
+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 { clearPendingAuth, pendingAuth, pendingAuthForEmail, savePendingAuth } from "./lib/auth-pending.js";
+import { configPath } from "./lib/paths.js";
+function withTempEnv(fn) {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-auth-pending-"));
+    try {
+        return fn({ ASKTHEW_DATA_DIR: dataDir });
+    }
+    finally {
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+}
+test("pending auth stores and resolves the request id for the matching email", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "Founder@Example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+            telemetryOptOut: true,
+        }, env);
+        const pending = pendingAuthForEmail("founder@example.com", env);
+        assert.equal(pending?.requestId, "request_1");
+        assert.equal(pending?.telemetryOptOut, true);
+        assert.equal(pendingAuth(env)?.email, "Founder@Example.com");
+    });
+});
+test("pending auth ignores other emails and clears expired requests", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "founder@example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() - 1_000).toISOString(),
+        }, env);
+        assert.equal(pendingAuthForEmail("other@example.com", env), null);
+        assert.equal(pendingAuthForEmail("founder@example.com", env), null);
+        const config = JSON.parse(fs.readFileSync(configPath(env), "utf8"));
+        assert.equal("pendingAuth" in config, false);
+    });
+});
+test("pending auth clear keeps the config file private and removes only pending auth", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "founder@example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+        }, env);
+        clearPendingAuth(env);
+        const config = JSON.parse(fs.readFileSync(configPath(env), "utf8"));
+        assert.equal("pendingAuth" in config, false);
+        assert.equal((fs.statSync(configPath(env)).mode & 0o777), 0o600);
+    });
+});

package/dist/cli-actions.test.d.ts

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

package/dist/cli-actions.test.js

@@ -0,0 +1,71 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LocalStore } from "./lib/local-store.js";
+import { buildWeeklyDigest, installPreCommitHook, preCommitDecisionGap, writeWeeklyDigest, } from "./lib/cli-actions.js";
+test("pre-commit gap detects staged implementation updates without linked decisions", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-hook-store-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    const signal = store.insertSignal({
+        sessionId: "s1",
+        sequence: 1,
+        kind: "implementation_update",
+        summary: "Changed onboarding page.",
+        filesTouched: ["apps/app/page.tsx"],
+        commandsRun: [],
+    });
+    const gap = preCommitDecisionGap({
+        store,
+        stagedFiles: ["apps/app/page.tsx"],
+        now: new Date(signal.capturedAt),
+    });
+    assert.equal(gap.missing, true);
+    assert.deepEqual(gap.matchedSignals, [signal.id]);
+    store.createDecision({
+        rawContent: "Keep onboarding page copy direct.",
+        sessionId: "s1",
+        sourceSignalIds: [signal.id],
+    });
+    const resolved = preCommitDecisionGap({
+        store,
+        stagedFiles: ["apps/app/page.tsx"],
+        now: new Date(signal.capturedAt),
+    });
+    assert.equal(resolved.missing, false);
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+test("pre-commit hook installer writes the documented inline prompt hook", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-hook-install-"));
+    execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+    const hookPath = installPreCommitHook({ cwd: dir });
+    const hook = fs.readFileSync(hookPath, "utf8");
+    assert.match(hook, /Ask The W pre-commit decision prompt/);
+    assert.match(hook, /@askthew\/mcp-plugin@latest hook-check --pre-commit/);
+    assert.equal((fs.statSync(hookPath).mode & 0o111) > 0, true);
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+test("weekly digest writes markdown with documented footer", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-digest-store-"));
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-digest-out-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    store.createDecision({
+        rawContent: "Ship the free-tier polish.",
+        sessionId: "s1",
+        status: "committed",
+    });
+    const now = new Date("2026-05-06T12:00:00.000Z");
+    const digest = buildWeeklyDigest({ store, now });
+    assert.match(digest, /# Ask The W Weekly Decision Digest 2026-19/);
+    assert.match(digest, /Ship the free-tier polish/);
+    assert.match(digest, /_Captured by Ask The W\._/);
+    const filePath = writeWeeklyDigest({ store, now, outputDir: outDir });
+    assert.equal(path.basename(filePath), "askthew-digest-2026-19.md");
+    assert.match(fs.readFileSync(filePath, "utf8"), /_Captured by Ask The W\._/);
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.rmSync(outDir, { recursive: true, force: true });
+});

package/dist/cli.d.ts

@@ -1,2 +1,11 @@
 #!/usr/bin/env node
+import { requestMagicLinkCode as requestMagicLinkCodeDefault, verifyMagicLinkCode as verifyMagicLinkCodeDefault } from "./lib/auth-magic-link.js";
+import { tryRegisterFreeInstall } from "./lib/free-install-registration.js";
+type AuthCommandDeps = {
+    log?: (message: string) => void;
+    requestMagicLinkCode?: typeof requestMagicLinkCodeDefault;
+    verifyMagicLinkCode?: typeof verifyMagicLinkCodeDefault;
+    registerFreeInstall?: typeof tryRegisterFreeInstall;
+};
+export declare function runAuthCommand(argv: string[], deps?: AuthCommandDeps): Promise<void>;
 export {};