vault-cortex 0.2.4 → 0.2.6

package/dist/init.js

@@ -4,7 +4,7 @@ import { buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages
 import { OBSIDIAN_SYNC_IMAGE, pollHealth } from "./docker.js";
 import { buildFilesToWrite, readEnvPort, writeFiles, } from "./scaffold.js";
 import { generateToken } from "./token.js";
-import { validateVaultPath } from "./vault.js";
+import { expandTilde, validateVaultPath } from "./vault.js";
 const DEFAULT_TARGET_DIR = "./vault-cortex";
 const isMode = (value) => value === "local" || value === "remote";
 const askMode = async (prompts) => {
@@ -68,16 +68,50 @@ const askVaultPath = async (prompts) => {
     }
     return validation.path;
 };
-/** Re-prompts until the answer is a plausible http(s) URL. */
+/**
+ * A trailing `/mcp` path segment, optionally followed by slashes, anchored to
+ * the end of a URL's pathname (`/MCP`, `/mcp/` match too via the `i` flag —
+ * WHATWG URL preserves path case). The server owns the `/mcp` endpoint and
+ * appends it when building the connect URL, so PUBLIC_URL must be the base
+ * origin; a re-included `/mcp` is rejected, not silently rewritten.
+ */
+const TRAILING_MCP_PATH = /\/mcp\/*$/i;
+/**
+ * Parses an http(s) URL with the WHATWG `URL` constructor, returning null for
+ * anything it can't be: bad syntax, a missing scheme, or a non-http(s)
+ * protocol (`ws:`, `file:`, ...). More robust than a `startsWith` check, which
+ * would pass malformed inputs like `https://` or `https://a b.com`.
+ */
+const parseHttpUrl = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Re-prompts until the answer is a valid base http(s) URL (no /mcp path). */
 const askPublicUrl = async (prompts) => {
-    const answer = await prompts.text("Public URL clients will use to reach this server:", {
+    const answer = await prompts.text("Public base URL clients will use to reach this server (no /mcp — it's added for you):", {
         placeholder: "https://vault.example.com or http://203.0.113.10:8000",
     });
     const trimmed = answer.trim();
-    if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
-        prompts.error("PUBLIC_URL must start with http:// or https://");
+    const url = parseHttpUrl(trimmed);
+    if (url === null) {
+        prompts.error("PUBLIC_URL must be a full http:// or https:// URL (e.g. https://vault.example.com).");
+        return askPublicUrl(prompts);
+    }
+    // Reject a re-included endpoint path instead of stripping it silently —
+    // PUBLIC_URL is the base origin and the server adds /mcp itself.
+    if (TRAILING_MCP_PATH.test(url.pathname)) {
+        prompts.error("Leave /mcp off PUBLIC_URL — it's the base URL and the server adds /mcp itself (e.g. https://vault.example.com).");
         return askPublicUrl(prompts);
     }
+    // Store the input as typed, trimming only a trailing slash so the connect
+    // URL is `${base}/mcp`, never `${base}//mcp`. URL's own normalization is
+    // unusable here: `.href` adds a trailing slash and `.origin` drops the path,
+    // so neither round-trips a reverse-proxy subpath like https://host/api.
     return trimmed.replace(/\/+$/, "");
 };
 /** Re-prompts until non-empty. */
@@ -169,13 +203,15 @@ const runLocalInit = async (flags, deps) => {
     const vaultPath = vaultPathResult !== undefined && vaultPathResult.kind !== "error"
         ? vaultPathResult.path
         : await askVaultPath(prompts);
-    const targetDir = resolve(flags.dir ??
+    // expandTilde before resolve: resolve() treats a leading `~` as a literal
+    // path segment, so a quoted "~/path" would create a directory named "~".
+    const targetDir = resolve(expandTilde(flags.dir ??
         (flags.yes
             ? DEFAULT_TARGET_DIR
             : await prompts.text("Where should I put the config files?", {
                 defaultValue: DEFAULT_TARGET_DIR,
                 placeholder: DEFAULT_TARGET_DIR,
-            })));
+            }))));
     const token = generateToken();
     // Conflict policy: identical existing files are skipped silently;
     // differing ones prompt per file (default keep). --yes never overwrites —
@@ -201,7 +237,7 @@ const runLocalInit = async (flags, deps) => {
     const started = flags.yes
         ? false
         : await offerComposeUp({ targetDir, port }, deps);
-    prompts.note(buildLocalConnectMessage({ targetDir, token, started, port, tokenWritten }), "Connect");
+    prompts.print(buildLocalConnectMessage({ targetDir, token, started, port, tokenWritten }));
     return 0;
 };
 // Remote flow (VPS + Obsidian Sync): resolve target dir → PUBLIC_URL →
@@ -211,11 +247,13 @@ const runLocalInit = async (flags, deps) => {
 // instructions. Always interactive — the sync-token step can't be defaulted.
 const runRemoteInit = async (flags, deps) => {
     const { prompts, docker } = deps;
-    const targetDir = resolve(flags.dir ??
+    // expandTilde before resolve: resolve() treats a leading `~` as a literal
+    // path segment, so a quoted "~/path" would create a directory named "~".
+    const targetDir = resolve(expandTilde(flags.dir ??
         (await prompts.text("Where should I put the config files?", {
             defaultValue: DEFAULT_TARGET_DIR,
             placeholder: DEFAULT_TARGET_DIR,
-        })));
+        }))));
     const publicUrl = await askPublicUrl(prompts);
     const vaultName = await askVaultName(prompts);
     // The Obsidian Sync token comes from an interactive docker run (the
@@ -263,14 +301,14 @@ const runRemoteInit = async (flags, deps) => {
     const started = obsidianAuthToken === ""
         ? false
         : await offerComposeUp({ targetDir, port }, deps);
-    prompts.note(buildRemoteConnectMessage({
+    prompts.print(buildRemoteConnectMessage({
         targetDir,
         token,
         publicUrl,
         started,
         obsidianTokenMissing: obsidianAuthToken === "",
         tokenWritten,
-    }), "Connect");
+    }));
     return 0;
 };
 export const runInit = async (flags, deps) => {

package/dist/messages.js

@@ -1,3 +1,12 @@
+import { styleText } from "node:util";
+// Strip styling when stdout isn't a color TTY (piped output, NO_COLOR, CI) so
+// captured/redirected output stays plain — no stray escape codes in copied
+// commands or logs.
+const paint = (style, text) => process.stdout.isTTY && !process.env.NO_COLOR ? styleText(style, text) : text;
+// Section header that replaces the old clack note box: a bold title over a
+// dim rule. The rule is its own line (not a per-line prefix), so it never
+// touches a copyable command.
+const connectHeader = () => `${paint("bold", "Connect")}\n${paint("dim", "─".repeat(56))}`;
 const composeUpCommand = (targetDir) => `cd ${targetDir} && docker compose up -d`;
 const startServerLine = (targetDir) => `Start the server:\n  ${composeUpCommand(targetDir)}`;
 /** Remote start line: running, blocked on the missing sync token, or ready to start. */
@@ -11,58 +20,82 @@ const remoteStartLine = (params) => {
     return startServerLine(targetDir);
 };
 /**
- * Local-mode "Connect" message. tokenWritten distinguishes whether this run's
- * generated token actually landed in .env — when an existing .env was kept,
- * the connect message must point at the token on disk instead of one that was never
- * saved (pasting it would fail auth with no hint why). port comes from the
- * .env on disk for the same reason: a kept file may override the default.
+ * Auth-token block shared by both modes. tokenWritten distinguishes whether
+ * this run's generated token actually landed in .env — when an existing .env
+ * was kept, the connect message must point at the token on disk instead of one
+ * that was never saved (pasting it would fail auth with no hint why). When the
+ * token was written, it goes alone on its own line so selecting that line
+ * copies just the token — no "Auth token: " prefix to trim.
+ */
+const tokenBlock = (params) => {
+    const { targetDir, token, tokenWritten } = params;
+    return tokenWritten
+        ? `${paint("dim", "Auth token:")}\n  ${paint("cyan", token)}`
+        : `${paint("dim", "Auth token:")} use the existing MCP_AUTH_TOKEN in ${targetDir}/.env`;
+};
+// ── Shared connect-message blocks ───────────────────────────────────────────
+// Both modes print the same skeleton; only the URL and the bits the topology
+// forces apart (start line, the Claude-apps caveat, optional-settings list,
+// docs link) differ. Sharing these blocks keeps the two messages in lockstep.
+// `mcpUrl` is the full endpoint (`<base>/mcp`); `healthUrl` is `<base>/healthz`.
+const connectUrlBlock = (mcpUrl, tokenLine) => `Connect your MCP client:
+  ${paint("dim", "URL:")}        ${paint("cyan", mcpUrl)}
+  ${tokenLine}`;
+// OAuth connect instruction + the Claude Code walkthrough — shared by every
+// variant. You register the server by its URL however your MCP client allows:
+// a CLI (`claude mcp add`, `opencode mcp add`), a connector dialog, or a
+// config file — then approve the consent page. Claude Code is the worked
+// example. The per-mode caveats (which clients need https, the localhost
+// bridge) are appended by the builders.
+const connectGuidance = (mcpUrl) => `Add the URL above as a remote MCP server (leave Client ID/Secret empty),
+then approve the consent page with the token. For example, Claude Code:
+  1. claude mcp add --scope user --transport http vault-cortex ${mcpUrl}
+  2. approve the browser consent page with the token above
+  3. done — the client holds auto-refreshing access tokens; the token
+     never sits in client config`;
+const curlGuidance = (mcpUrl) => `Clients without OAuth, scripts, and curl send the token directly:
+  curl -H "Authorization: Bearer <token>" ${mcpUrl}`;
+const smokeTest = (healthUrl) => `Smoke test:
+  curl ${healthUrl}`;
+/**
+ * Local-mode "Connect" message. port comes from the .env on disk: a kept file
+ * may override the default, so the message must describe the server that will
+ * actually run.
  */
 export const buildLocalConnectMessage = (params) => {
     const { targetDir, token, started, port, tokenWritten } = params;
+    const baseUrl = `http://localhost:${port}`;
     const startLine = started
         ? "The server is running."
         : startServerLine(targetDir);
-    // When the token was written, put it alone on its own line so selecting
-    // that line copies just the token — no "Auth token: " prefix to trim and
-    // no chance of grabbing the surrounding label.
-    const tokenLine = tokenWritten
-        ? `Auth token:\n  ${token}`
-        : `Auth token: use the existing MCP_AUTH_TOKEN in ${targetDir}/.env`;
-    // Flush-left on purpose: template literals keep leading whitespace, so
-    // indenting these lines would indent the rendered output.
-    const connectMessage = `${startLine}
-
-Connect your MCP client:
-  URL:        http://localhost:${port}/mcp
-  ${tokenLine}
-
-Claude Code:
-  1. claude mcp add --transport http vault-cortex http://localhost:${port}/mcp
-  2. Approve the browser consent page with the token above
-  3. Done. The client holds auto-refreshing access tokens; the
-     token never sits in client config
-
-Claude Desktop only accepts https URLs in its connector dialog, so
-register the server in claude_desktop_config.json via the mcp-remote
-bridge instead:
+    const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
+    // Flush-left on purpose: this is printed as plain text (see paint), so
+    // leading whitespace would render as literal indentation. Local is always
+    // localhost http, so it shares the http guidance; its only divergences are
+    // that claude.ai can't reach localhost at all and Claude Desktop needs the
+    // mcp-remote bridge (the dialog rejects http, but mcp-remote exempts
+    // localhost, so no --allow-http).
+    const connectMessage = `${connectHeader()}
+
+${startLine}
+
+${connectUrlBlock(`${baseUrl}/mcp`, tokenLine)}
+
+${connectGuidance(`${baseUrl}/mcp`)}
+
+Other clients (opencode, Cursor, …) take the URL above too. claude.ai
+(web) can't reach localhost — connect from a client on this machine.
+Claude Desktop only accepts https URLs in its connector dialog, so bridge
+it with mcp-remote:
   "vault-cortex": {
     "command": "npx",
-    "args": ["-y", "mcp-remote", "http://localhost:${port}/mcp",
+    "args": ["-y", "mcp-remote", "${baseUrl}/mcp",
       "--header", "Authorization: Bearer <token above>"]
   }
 
-Other OAuth clients (Cursor, most MCP clients) add the URL above as a
-remote MCP server, leaving Client ID/Secret empty ("remote" = HTTP —
-the server still runs on your machine), then approve the consent page.
-
-Clients without OAuth, scripts, and curl send the token directly:
-  curl -H "Authorization: Bearer <token>" http://localhost:${port}/mcp
+${curlGuidance(`${baseUrl}/mcp`)}
 
-Note: claude.ai (web) cannot reach localhost — use Claude Code for local
-access, or Claude Desktop with the mcp-remote bridge.
-
-Smoke test:
-  curl http://localhost:${port}/healthz
+${smokeTest(`${baseUrl}/healthz`)}
 
 Optional settings (timezone, memory folder, port, logging) are commented
 out in ${targetDir}/.env — uncomment, set a value, then apply with
@@ -72,8 +105,9 @@ Full docs: https://github.com/aliasunder/vault-cortex/blob/main/deploy/local/REA
     return connectMessage;
 };
 /**
- * Remote-mode "Connect" message. See buildLocalConnectMessage for the tokenWritten
- * rationale; remote URLs come from PUBLIC_URL, so no port handling here.
+ * Remote-mode "Connect" message. See buildLocalConnectMessage for the
+ * tokenWritten rationale; remote URLs come from PUBLIC_URL, so no port
+ * handling here.
  */
 export const buildRemoteConnectMessage = (params) => {
     const { targetDir, token, publicUrl, started, obsidianTokenMissing, tokenWritten, } = params;
@@ -82,27 +116,36 @@ export const buildRemoteConnectMessage = (params) => {
         started,
         obsidianTokenMissing,
     });
-    const approveLine = tokenWritten
-        ? `approve with your MCP_AUTH_TOKEN:\n  ${token}`
-        : `approve with the existing MCP_AUTH_TOKEN in ${targetDir}/.env`;
-    const httpUrlWarning = publicUrl.startsWith("https://")
-        ? ""
-        : `
-
-Note: claude.ai and Claude Desktop only accept https URLs — set up
-HTTPS when you're ready for those clients (see the HTTPS section in
-the remote guide). Claude Code works with http:
-  claude mcp add --transport http vault-cortex ${publicUrl}/mcp`;
-    // Flush-left on purpose: template literals keep leading whitespace, so
-    // indenting these lines would indent the rendered output.
-    const connectMessage = `${startLine}
-
-Connect your MCP client:
-  URL: ${publicUrl}/mcp
-
-OAuth clients (Claude Desktop, Claude Code, claude.ai): add a remote MCP
-server with that URL and leave Client ID/Secret empty — a consent page
-opens; ${approveLine}${httpUrlWarning}
+    const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
+    // Both branches share the connect walkthrough; only the caveat differs. Over
+    // https every client converges — nothing to set up. Over http the Claude
+    // apps' connector dialog needs TLS while other clients are fine. We already
+    // know which case it is, so the http branch states it rather than asking.
+    // Case-insensitive: askPublicUrl stores the scheme as typed, so an HTTPS://
+    // input is valid and must still route to the https branch.
+    const clientGuidance = publicUrl.toLowerCase().startsWith("https://")
+        ? `${connectGuidance(`${publicUrl}/mcp`)}
+
+Reachable over https from any MCP client — Claude Desktop, claude.ai (web
+and mobile), opencode, Cursor — from any device.`
+        : `${connectGuidance(`${publicUrl}/mcp`)}
+
+Other clients (opencode, Cursor, …) work over http too. claude.ai and
+Claude Desktop only accept https URLs — set up HTTPS for those clients
+(see the HTTPS section in the remote guide).`;
+    // Flush-left on purpose: this is printed as plain text (see paint), so
+    // leading whitespace would render as literal indentation.
+    const connectMessage = `${connectHeader()}
+
+${startLine}
+
+${connectUrlBlock(`${publicUrl}/mcp`, tokenLine)}
+
+${clientGuidance}
+
+${curlGuidance(`${publicUrl}/mcp`)}
+
+${smokeTest(`${publicUrl}/healthz`)}
 
 Optional settings (timezone, memory folder, port, logging, sync
 behavior) are commented out in ${targetDir}/.env — uncomment, set a

package/dist/prompts.js

@@ -19,6 +19,9 @@ export const createPrompts = () => ({
     intro: (message) => clack.intro(message),
     outro: (message) => clack.outro(message),
     note: (message, title) => clack.note(message, title),
+    // Leading + trailing newline sets the block off from the surrounding clack
+    // output without a box around it.
+    print: (message) => process.stdout.write(`\n${message}\n`),
     log: (message) => clack.log.info(message),
     warn: (message) => clack.log.warn(message),
     error: (message) => clack.log.error(message),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-cortex",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Set up a Vault Cortex MCP server for your Obsidian vault in one command: npx vault-cortex init",
   "license": "MIT",
   "type": "module",