pattern-mcp 0.11.0 → 0.12.1

package/README.md

@@ -15,10 +15,13 @@ design reference.
 
 [Website](https://usepattern.sh) · [npm](https://www.npmjs.com/package/pattern-mcp) · [Report an issue](https://github.com/donaldrichard19-LVD/pattern-mcp/issues/new/choose)
 
-**Current release: v0.10.0** — adds an opt-in enforcement boundary (a
-`PreToolUse` hook plus a paired CI check) so a new component decision can
-be required, not just logged. See [Enforcement boundary: hook + CI
-gate](#enforcement-boundary-hook--ci-gate).
+**Current release: v0.12.0** — When you run `npx pattern-mcp` for the
+first time, Pattern now shows the optional enforcement boundary
+alongside the telemetry notice. This boundary includes a `PreToolUse`
+hook and a matching CI check. Together, they can require a decision for
+each new component instead of only recording it. See
+[Enforcement boundary: hook + CI gate](#enforcement-boundary-hook--ci-gate)
+for more details.
 
 <details>
 <summary><strong>Contents</strong> (click to expand)</summary>
@@ -1636,6 +1639,31 @@ Run non-interactively with `--yes` (accepts every safe default; branch
 protection is never auto-confirmed even then -- it's the one step that
 reaches outside your local filesystem into real, shared GitHub config).
 
+**You don't have to find this section to learn this exists.** Every
+`npx pattern-mcp` run surfaces it at the same first-run moment as the
+[telemetry notice](#telemetry):
+
+- **Always**, in every context, including when a real MCP client has
+  spawned this as a subprocess: a one-time, non-blocking stderr mention
+  that the enforcement boundary exists and the command above sets it up.
+  Same "prints once, gated by a marker file" discipline as the telemetry
+  notice -- tracked at `~/.pattern/enforcement_notice_shown`
+  (`PATTERN_ENFORCEMENT_NOTICE_PATH` to override), never repeats after
+  that regardless of whether you act on it.
+- **Only when stdin is a real terminal** (`process.stdin.isTTY`) --
+  meaning a human ran `npx pattern-mcp` bare in their own shell, never
+  true for a real MCP client's spawned subprocess -- it also offers a
+  genuine interactive prompt right there: *"Set it up now?"* A yes runs
+  the exact same `init` flow described above. The same JSON-RPC-channel
+  constraint that rules out an interactive telemetry prompt (see
+  [Telemetry](#telemetry)) applies here too, which is why this only ever
+  asks when nothing is piping protocol messages into stdin to begin
+  with.
+
+Set `PATTERN_NO_ENFORCEMENT_NOTICE` to suppress both halves. See
+`offerEnforcementSetupOnce` in `src/init-enforcement.ts` for the
+implementation.
+
 **Or set it up by hand**, two pieces, neither installed automatically:
 
 - **`.claude/settings.json`** wired to run `npx --yes
@@ -1772,7 +1800,9 @@ whether you act on it. There's no interactive y/n prompt: Pattern's stdin
 is the MCP JSON-RPC channel the client uses to talk to it, so blocking on
 stdin for a keypress would fight the protocol handshake instead of
 showing a dialog -- a stderr notice is the safe equivalent for a stdio
-MCP server.
+MCP server. The same first-run moment also surfaces the enforcement
+boundary, with the same constraint handled the same way -- see
+[Enforcement boundary: hook + CI gate](#enforcement-boundary-hook--ci-gate).
 
 **Why it exists.** Three things about real usage can't be answered from
 this repo alone: whether people actually come back and use Pattern on a

package/dist/index.js

@@ -38,6 +38,7 @@ import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { captureApiError, captureRecommendation, getClient as getPostHogClient, installId, printTelemetryNoticeOnce, shutdownTelemetry, TELEMETRY_ENABLED, } from "./telemetry.js";
+import { offerEnforcementSetupOnce } from "./init-enforcement.js";
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Only required for org-scoped keys (not tied to one workspace); unset for
 // legacy workspace-scoped keys, which don't need it.
@@ -3864,6 +3865,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 async function main() {
     printTelemetryNoticeOnce();
+    // Piggybacks on this same first-run moment (Option B, see
+    // init-enforcement.ts) -- always prints a one-time, non-blocking mention;
+    // only prompts interactively when stdin is a real TTY, never when a real
+    // MCP client has piped stdio into this process for JSON-RPC. Always
+    // returns before the transport below claims stdin.
+    await offerEnforcementSetupOnce(PROJECT_ROOT);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Best-effort telemetry drain on clean shutdown -- no-op when telemetry

package/dist/init-enforcement.js

@@ -12,6 +12,7 @@
 // post_ledger_provenance_to_github.
 import { execFileSync } from "node:child_process";
 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";
@@ -314,3 +315,71 @@ export async function runInit(root, options) {
     }
     console.log("\nDone. Review the changes with `git status` / `git diff`, then commit when ready.");
 }
+// Option B from BACKLOG.md's "Enforcement boundary setup" entry: piggyback
+// on the moment someone's already setting Pattern up, rather than leaving
+// enforcement as something only the README mentions. Called once from
+// index.ts's main(), right alongside printTelemetryNoticeOnce, before the
+// stdio transport connects.
+//
+// The literal original phrasing of this option ("extend the first-run
+// notice into a [y/N] prompt") turns out not to be safely buildable as
+// written: stdin is the live JSON-RPC channel a real MCP client uses to
+// talk to this process (see telemetry.ts's printTelemetryNoticeOnce for
+// the same constraint, stated first). Blocking it on a keypress here would
+// fight the protocol handshake, not show a dialog. So this does two
+// different things depending on how stdin is actually connected:
+//
+//  - Always (any context, including a real client subprocess): print a
+//    one-time, non-blocking mention that the enforcement boundary exists
+//    and how to set it up. Same "print once, gated by a marker file"
+//    pattern as the telemetry notice, deliberately a separate marker/
+//    message so the two stay independently legible in a terminal.
+//  - Only when process.stdin.isTTY is true -- which a real MCP client's
+//    spawned subprocess never has, since it always pipes stdio to speak
+//    JSON-RPC over it, but a human running `npx pattern-mcp` bare in
+//    their own terminal does -- also offer a real interactive prompt,
+//    reusing runInit itself rather than duplicating its logic.
+const ENFORCEMENT_NOTICE_PATH = process.env.PATTERN_ENFORCEMENT_NOTICE_PATH ?? join(homedir(), ".pattern", "enforcement_notice_shown");
+export async function offerEnforcementSetupOnce(root) {
+    if (process.env.PATTERN_NO_ENFORCEMENT_NOTICE)
+        return;
+    try {
+        readFileSync(ENFORCEMENT_NOTICE_PATH, "utf8");
+        return; // Already shown -- never repeat, same discipline as the telemetry notice.
+    }
+    catch {
+        // No marker yet -- fall through and show it.
+    }
+    console.error([
+        "",
+        "Pattern -- enforcement boundary available (this will not print again)",
+        "By default, Pattern is something the calling agent chooses to use.",
+        "An opt-in hook + CI check can require it instead: run `npx pattern-check-gate init`",
+        "in your repo to set it up.",
+        "Full details: https://github.com/donaldrichard19-LVD/pattern-mcp#enforcement-boundary-hook--ci-gate",
+        "",
+    ].join("\n"));
+    try {
+        mkdirSync(dirname(ENFORCEMENT_NOTICE_PATH), { recursive: true });
+        writeFileSync(ENFORCEMENT_NOTICE_PATH, new Date().toISOString(), "utf8");
+    }
+    catch {
+        // Couldn't persist the marker -- worst case this prints again next
+        // run. Never blocks startup over it, same as the telemetry notice.
+    }
+    if (!process.stdin.isTTY)
+        return;
+    try {
+        const setUpNow = await confirm("Set it up now?", { yes: false }, false);
+        if (setUpNow) {
+            await runInit(root, { yes: false }); // closes the shared readline itself, in its own finally block
+        }
+    }
+    finally {
+        // closeRl() is safe to call even if runInit already closed it (checks
+        // rl?.close() and no-ops on null) -- this just guarantees stdin is
+        // always released back before main() connects the stdio transport,
+        // whether the answer was no or runInit already cleaned up after itself.
+        closeRl();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "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",