pattern-mcp 0.12.1 → 0.14.0

package/dist/init-enforcement.js

@@ -15,68 +15,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline";
 import { deriveProjectId } from "./project-id.js";
+import { closeRl, confirm, promptText, shellQuote } from "./prompt.js";
 const HOOK_MARKER = "pattern-check-gate-hook";
-// A queue-based prompt helper, not readline/promises' question() --
-// question() only starts listening for a line *after* it's called, but
-// with piped/non-TTY stdin (as in an automated test, or `init | cat`)
-// every line arrives in one synchronous burst, ahead of any await
-// cycle. Confirmed directly: two sequential `rl.question()` calls on a
-// piped `printf 'a\nb\n'` answer only the first and hang forever on the
-// second -- Node even logs "Detected unsettled top-level await" in that
-// repro. The fix is a small always-listening queue: a persistent 'line'
-// listener buffers answers that arrive before they're asked for, so
-// `askLine` either drains an already-buffered answer immediately or
-// waits for the next 'line' event, whichever comes first -- correct for
-// both a real interactive TTY (waiter path) and piped/scripted input
-// (queue path).
-let rl = null;
-const lineQueue = [];
-const waiters = [];
-function ensureRl() {
-    if (!rl) {
-        rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.on("line", (line) => {
-            const waiter = waiters.shift();
-            if (waiter)
-                waiter(line);
-            else
-                lineQueue.push(line);
-        });
-    }
-    return rl;
-}
-function askLine(promptStr) {
-    ensureRl();
-    process.stdout.write(promptStr);
-    const queued = lineQueue.shift();
-    if (queued !== undefined)
-        return Promise.resolve(queued);
-    return new Promise((resolve) => waiters.push(resolve));
-}
-function closeRl() {
-    rl?.close();
-    rl = null;
-}
-async function confirm(question, options, defaultYes) {
-    if (options.yes)
-        return defaultYes;
-    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
-    const answer = (await askLine(`${question} ${suffix} `)).trim().toLowerCase();
-    if (!answer)
-        return defaultYes;
-    return answer === "y" || answer === "yes";
-}
-async function promptText(question, defaultValue, options) {
-    if (options.yes)
-        return defaultValue;
-    const answer = (await askLine(`${question} [${defaultValue}]: `)).trim();
-    return answer || defaultValue;
-}
-function shellQuote(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 async function setupClaudeSettings(root, projectIdOverride, options) {
     const settingsPath = join(root, ".claude", "settings.json");
     let settings = {};

package/dist/prompt.js

@@ -0,0 +1,65 @@
+// Shared interactive-prompt plumbing for Pattern's CLI wizards
+// (`pattern-check-gate init`, `pattern-mcp init`). Extracted from
+// init-enforcement.ts so both wizards share one readline instance and one
+// fix for the same bug, instead of drifting apart.
+//
+// A queue-based prompt helper, not readline/promises' question() --
+// question() only starts listening for a line *after* it's called, but
+// with piped/non-TTY stdin (as in an automated test, or `init | cat`)
+// every line arrives in one synchronous burst, ahead of any await
+// cycle. Confirmed directly: two sequential `rl.question()` calls on a
+// piped `printf 'a\nb\n'` answer only the first and hang forever on the
+// second -- Node even logs "Detected unsettled top-level await" in that
+// repro. The fix is a small always-listening queue: a persistent 'line'
+// listener buffers answers that arrive before they're asked for, so
+// `askLine` either drains an already-buffered answer immediately or
+// waits for the next 'line' event, whichever comes first -- correct for
+// both a real interactive TTY (waiter path) and piped/scripted input
+// (queue path).
+import { createInterface } from "node:readline";
+let rl = null;
+const lineQueue = [];
+const waiters = [];
+function ensureRl() {
+    if (!rl) {
+        rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.on("line", (line) => {
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                lineQueue.push(line);
+        });
+    }
+    return rl;
+}
+export function askLine(promptStr) {
+    ensureRl();
+    process.stdout.write(promptStr);
+    const queued = lineQueue.shift();
+    if (queued !== undefined)
+        return Promise.resolve(queued);
+    return new Promise((resolve) => waiters.push(resolve));
+}
+export function closeRl() {
+    rl?.close();
+    rl = null;
+}
+export async function confirm(question, options, defaultYes) {
+    if (options.yes)
+        return defaultYes;
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    const answer = (await askLine(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer)
+        return defaultYes;
+    return answer === "y" || answer === "yes";
+}
+export async function promptText(question, defaultValue, options) {
+    if (options.yes)
+        return defaultValue;
+    const answer = (await askLine(`${question} [${defaultValue}]: `)).trim();
+    return answer || defaultValue;
+}
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/telemetry.js

@@ -18,10 +18,12 @@
  *     install ID (see installId() below); a one-way SHA-256 hash of
  *     project_id, truncated to 16 hex chars -- never the raw project_id
  *     string; the verdict shape already written to the local call log
- *     (verdict, confidence, ensemble_triggered, estimated cost); and, on a
+ *     (verdict, confidence, ensemble_triggered, estimated cost); on a
  *     failed Anthropic API call, only the HTTP status and a coarse error
  *     classification (rate_limit / insufficient_credit / other) -- never
- *     the request or response body.
+ *     the request or response body; and, on every invocation of the
+ *     binary, a single `pattern_cli_started` event carrying only which
+ *     mode it ran in (`server` or `init`) -- see captureCliStarted below.
  *  2. `@posthog/mcp`'s standard MCP instrumentation, wired up in index.ts:
  *     tool name, call duration, error/success, and the same anonymous
  *     install ID as the distinct_id (via its `identify` option), so both
@@ -34,6 +36,15 @@
  * itself are never sent, by either half. See SECURITY.md and README.md for
  * the full disclosure and how to opt out.
  *
+ * Manual/ad-hoc test sessions (a one-off MCP client run by hand while
+ * debugging, not a checked-in script) should set PATTERN_TELEMETRY=0 before
+ * connecting -- there's no way for this file to distinguish that from real
+ * usage on its own, and self-testing was previously showing up as if it
+ * were adoption (see project_pattern_activation_funnel memory: roughly half
+ * of all recorded handshakes turned out to be internal test/smoke-test
+ * clients). Checked-in test scripts (e.g. scripts/test-client.mjs) default
+ * this off already.
+ *
  * Reuses Pattern's existing PostHog project (the same one the marketing
  * site sends browser events to) with its public, write-only project key --
  * safe to embed in a distributed package the same way that key is already
@@ -83,10 +94,12 @@ export function printTelemetryNoticeOnce() {
         "When on, Pattern sends an anonymous per-install ID, a one-way hash",
         "of project_id (never the raw string), the same verdict summary",
         "already written to ~/.pattern/calls.log (verdict, confidence,",
-        "reason, estimated cost), and standard MCP tool-call analytics (tool",
-        "name, duration, success/failure) via PostHog's MCP SDK. Tool call",
-        "arguments and responses are stripped before sending -- component_need,",
-        "domain, framework, existing_stack, and your API key are never sent.",
+        "reason, estimated cost), a single startup event noting whether this",
+        "run is the server or the `init` wizard, and standard MCP tool-call",
+        "analytics (tool name, duration, success/failure) via PostHog's MCP",
+        "SDK. Tool call arguments and responses are stripped before sending",
+        "-- component_need, domain, framework, existing_stack, and your API",
+        "key are never sent.",
         "Full field list: https://github.com/donaldrichard19-LVD/pattern-mcp#telemetry",
         "",
         "To opt out: PATTERN_TELEMETRY=0",
@@ -216,6 +229,35 @@ export function captureRecommendation(args) {
         served_from_ledger: args.servedFromLedger ?? false,
     });
 }
+// Fires once per process invocation, immediately at startup, before the
+// stdio transport connects and before either first-run notice prints.
+// Distinct from @posthog/mcp's $mcp_initialize (which only fires once a
+// real MCP client completes the JSON-RPC handshake): this fires for
+// every real execution of the binary, including a bare `npx pattern-mcp`
+// run in a terminal that never gets wired into a client, and the `init`
+// subcommand. Exists to measure the gap between "npm registered a
+// download" (includes scanner/mirror traffic that never runs the code at
+// all) and "someone actually ran this" -- see
+// project_pattern_reddit_launch_spike memory for why that gap mattered:
+// a 2026-09-11 download spike showed almost no matching $mcp_initialize
+// growth, and there was no signal at all for the step in between.
+export function captureCliStarted(mode) {
+    capture("pattern_cli_started", { mode });
+}
+// Paired with captureCliStarted so a start with no matching handshake is
+// diagnosable instead of silent -- added after a 2026-09-13 incident where
+// 33 starts in one hour produced exactly 1 successful handshake, and
+// telemetry had no way to say why the other 32 processes ended (see
+// project_pattern_activation_funnel memory). Only a coarse reason and the
+// thrown value's constructor name travel -- never the error message or
+// stack, which could contain a file path, a stray argument value, or other
+// local detail never sent by design (see this file's header).
+export function captureCliExited(reason, err) {
+    capture("pattern_cli_exited", {
+        exit_reason: reason,
+        error_name: err instanceof Error ? err.name : null,
+    });
+}
 export function captureApiError(args) {
     const { type, status } = classifyApiError(args.message);
     capture("pattern_cli_api_error", {
@@ -225,13 +267,27 @@ export function captureApiError(args) {
         project_hash: args.projectId ? hashProjectId(args.projectId) : null,
     });
 }
+// How long shutdown will wait for a final flush before giving up.
+// Verified directly (not assumed): with an unreachable PostHog host,
+// posthog-node's client.shutdown() does not reject or time out on its
+// own -- it hung well past 8s in a real test (an unroutable/blocked port
+// looks like a stalled TCP connect, not an instant refusal). Without this
+// race, every caller of shutdownTelemetry -- the SIGINT/SIGTERM handlers
+// below AND the `init` wizard's normal exit path -- would hang
+// indefinitely on a restricted network instead of exiting, directly
+// contradicting this function's own "best-effort, never blocks" purpose.
+const SHUTDOWN_TIMEOUT_MS = 2000;
 // Best-effort drain on clean shutdown so the last event(s) of a session
 // aren't dropped. Safe to call even when telemetry was never enabled.
+// Always resolves within SHUTDOWN_TIMEOUT_MS regardless of network state.
 export async function shutdownTelemetry() {
     if (!client)
         return;
     try {
-        await client.shutdown();
+        await Promise.race([
+            client.shutdown(),
+            new Promise((resolve) => setTimeout(resolve, SHUTDOWN_TIMEOUT_MS).unref()),
+        ]);
     }
     catch {
         // Ignore -- process is exiting either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "MCP server that turns your design guidance into a checkable process -- evaluates UI components from external libraries (shadcn/ui, 21st.dev, ReUI) or your own registered design system against a requirements checklist, then tells the agent whether to reuse an existing component or build one from a concrete design reference.",
   "type": "module",
   "main": "dist/index.js",