vault-cortex 0.10.2 → 0.10.3-beta.52

package/dist/docker.js

@@ -86,7 +86,10 @@ export const buildDockerRunArgs = (params) => {
         args.push("--health-interval", "15s");
         args.push("--health-timeout", "5s");
         args.push("--health-retries", "5");
-        args.push("--health-start-period", "60s");
+        // 180s: the remote image's init chain runs the first vault sync to
+        // completion before the MCP server boots, so /healthz appears late on
+        // fresh deploys.
+        args.push("--health-start-period", "180s");
         args.push("--log-driver", "json-file");
         args.push("--log-opt", "max-size=10m");
         args.push("--log-opt", "max-file=3");
@@ -191,6 +194,28 @@ export const probeHealth = async (params, fetchFn) => {
         return false;
     }
 };
+/**
+ * Health-poll budget by deployment mode. Remote gets a longer window because
+ * the container's init chain runs the first vault sync to completion before
+ * the server boots — /healthz can legitimately take minutes to appear on a
+ * fresh deploy (matches the 180s container health start period plus boot
+ * margin).
+ */
+export const healthPollTimeoutMs = (mode) => {
+    return mode === "remote" ? 240_000 : 120_000;
+};
+/** Health-poll failure message with the duration derived from the actual
+ *  timeout, so mode-specific budgets can't drift out of the copy. Remote
+ *  adds a first-sync hint: the container's init chain retries the first
+ *  sync with no upper time bound, so an expired poll does not mean the
+ *  server failed — it may flip healthy after the CLI stops waiting. */
+export const healthTimeoutMessage = (mode, timeoutMs) => {
+    const baseMessage = `Server did not respond within ${timeoutMs / 60_000} minutes — check: docker logs ${CONTAINER_NAME}`;
+    if (mode === "remote") {
+        return `${baseMessage} (a long first sync may still be running — the container keeps starting in the background)`;
+    }
+    return baseMessage;
+};
 /**
  * Polls the health endpoint until it responds OK or the timeout elapses.
  * The first `docker run` pulls the image, so the default window is generous.

package/dist/init.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { buildLocalEnv, buildRemoteEnv } from "./env.js";
 import { captureObsidianToken } from "./get-sync-token.js";
 import { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, buildLocalConnectMessage, buildRemoteConnectMessage, startCommand, } from "./messages.js";
-import { pollHealth } from "./docker.js";
+import { healthPollTimeoutMs, healthTimeoutMessage, pollHealth, } from "./docker.js";
 import { reportPublicUrlProbe } from "./lifecycle.js";
 import { applyOptionalSettings, askOptionalSettings, derivePublicUrlOverride, } from "./optional-settings.js";
 import { buildFilesToWrite, readEnvPort, readEnvPublicUrl, writeFiles, } from "./scaffold.js";
@@ -154,8 +154,9 @@ const reportWrites = (params, prompts) => {
 /**
  * Offers to start the container, walking a gate ladder where each failed
  * gate degrades to instructions instead of an error: daemon running → user
- * consents → docker run succeeds → health check passes. Returns true only
- * when the server is confirmed up.
+ * consents → docker run succeeds → health check passes. Returns "running"
+ * when the server is confirmed up, "starting" when the container launched
+ * but the health check timed out, or "not-started" when a gate failed.
  */
 const offerDockerRun = async (params, deps) => {
     const { targetDir, port, mode, vaultPath } = params;
@@ -168,11 +169,11 @@ const offerDockerRun = async (params, deps) => {
                 nextStep: `\nThen start the server with:\n  ${startHint}`,
             })
             : buildDaemonNotRunningMessage(`, then run:\n  ${startHint}`));
-        return false;
+        return "not-started";
     }
     const startNow = await prompts.confirm("Start the server now?", true);
     if (!startNow)
-        return false;
+        return "not-started";
     const containerStarted = docker.dockerRun({
         mode,
         envFilePath: join(targetDir, ".env"),
@@ -181,17 +182,18 @@ const offerDockerRun = async (params, deps) => {
     });
     if (!containerStarted) {
         prompts.error("docker run failed — see output above.");
-        return false;
+        return "not-started";
     }
     const spinner = prompts.spinner();
     spinner.start("Waiting for the server to come up (first run may take a moment)");
-    const healthy = await pollHealth({ url: `http://127.0.0.1:${port}/healthz` }, fetchFn);
+    const timeoutMs = healthPollTimeoutMs(mode);
+    const healthy = await pollHealth({ url: `http://127.0.0.1:${port}/healthz`, timeoutMs }, fetchFn);
     if (!healthy) {
-        spinner.stop("Server did not respond within 2 minutes — check: docker logs vault-cortex");
-        return false;
+        spinner.stop(healthTimeoutMessage(mode, timeoutMs));
+        return "starting";
     }
     spinner.stop("Server is up — health check passed.");
-    return true;
+    return "running";
 };
 // Local flow: resolve vault path → resolve target dir → generate token →
 // write .env → optionally start the container → print connect instructions.
@@ -270,10 +272,16 @@ const runLocalInit = async (flags, deps) => {
         prompts.log("Generated MCP auth token (saved to .env).");
     const port = readEnvPort(join(targetDir, ".env"));
     // --yes is for scripts/CI, so it never starts Docker.
-    const started = flags.yes
-        ? false
+    const startStatus = flags.yes
+        ? "not-started"
         : await offerDockerRun({ targetDir, port, mode: "local", vaultPath }, deps);
-    prompts.print(buildLocalConnectMessage({ targetDir, token, started, port, tokenWritten }));
+    prompts.print(buildLocalConnectMessage({
+        targetDir,
+        token,
+        startStatus,
+        port,
+        tokenWritten,
+    }));
     return 0;
 };
 // Remote flow (VPS + Obsidian Sync): resolve target dir → PUBLIC_URL →
@@ -346,12 +354,12 @@ const runRemoteInit = async (flags, deps) => {
     const effectivePublicUrl = readEnvPublicUrl(join(targetDir, ".env")) ?? publicUrl;
     // Without the sync token the container can't start (init-check-auth fails
     // and s6 stops it), so only offer docker run when it was provided.
-    const started = obsidianAuthToken === ""
-        ? false
+    const startStatus = obsidianAuthToken === ""
+        ? "not-started"
         : await offerDockerRun({ targetDir, port, mode: "remote" }, deps);
     // The container check above hit localhost on this machine; the public URL
     // is the ingress path clients actually use — probe it too, informationally.
-    if (started) {
+    if (startStatus === "running") {
         await reportPublicUrlProbe(effectivePublicUrl, {
             prompts,
             fetchFn: deps.fetchFn,
@@ -361,7 +369,7 @@ const runRemoteInit = async (flags, deps) => {
         targetDir,
         token,
         publicUrl: effectivePublicUrl,
-        started,
+        startStatus,
         obsidianTokenMissing: obsidianAuthToken === "",
         tokenWritten,
     }));

package/dist/lifecycle.js

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-import { CONTAINER_NAME, pollHealth, probeHealth, } from "./docker.js";
+import { CONTAINER_NAME, healthPollTimeoutMs, healthTimeoutMessage, pollHealth, probeHealth, } from "./docker.js";
 import { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, } from "./messages.js";
 import { detectMode, hasEnvPublicUrl, readEnvPort, readEnvPublicUrl, readEnvVaultPath, } from "./scaffold.js";
 import { expandTilde } from "./vault.js";
@@ -123,12 +123,13 @@ export const recreateContainer = async (params, deps) => {
     }
     const spinner = prompts.spinner();
     spinner.start("Waiting for the server to come up");
+    const timeoutMs = healthTimeoutMs ?? healthPollTimeoutMs(deployment.mode);
     const healthy = await pollHealth({
         url: `http://127.0.0.1:${deployment.port}/healthz`,
-        timeoutMs: healthTimeoutMs,
+        timeoutMs,
     }, fetchFn);
     if (!healthy) {
-        spinner.stop(`Server did not respond within 2 minutes — check: docker logs ${CONTAINER_NAME}`);
+        spinner.stop(healthTimeoutMessage(deployment.mode, timeoutMs));
         return 1;
     }
     spinner.stop("Server is up — health check passed.");

package/dist/messages.js

@@ -1,4 +1,5 @@
 import { styleText } from "node:util";
+import { CONTAINER_NAME } from "./docker.js";
 // Strip styling when stdout isn't a color TTY (piped output, CI) or NO_COLOR
 // is set (any value, including empty — per the NO_COLOR spec) so
 // captured/redirected output stays plain — no stray escape codes in copied
@@ -50,11 +51,14 @@ const upgradeCommand = (targetDir) => `npx vault-cortex@latest upgrade --dir "${
 // have. `start` runs the same re-create cycle and pulls the image on demand.
 export const startCommand = (targetDir) => `npx vault-cortex@latest start --dir "${targetDir}"`;
 const startServerLine = (targetDir) => `Start the server:\n  ${startCommand(targetDir)}`;
-/** Remote start line: running, blocked on the missing sync token, or ready to start. */
+const startingInBackgroundLine = () => `The server is starting in the background — check progress:\n  docker logs ${CONTAINER_NAME}`;
+/** Remote start line: running, starting, blocked on the missing sync token, or ready to start. */
 const remoteStartLine = (params) => {
-    const { targetDir, started, obsidianTokenMissing } = params;
-    if (started)
+    const { targetDir, startStatus, obsidianTokenMissing } = params;
+    if (startStatus === "running")
         return "The server is running.";
+    if (startStatus === "starting")
+        return startingInBackgroundLine();
     if (obsidianTokenMissing) {
         return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${startCommand(targetDir)}`;
     }
@@ -99,13 +103,14 @@ const curlGuidance = (mcpUrl) => `Clients without OAuth, scripts, and curl send
 const smokeTest = (healthUrl) => `Smoke test:
   curl ${healthUrl}`;
 /**
- * Remote health-check block. Started: the CLI verified localhost on the VPS,
- * but the public URL is a different check (ingress — DNS, TLS, proxy), so the
- * command stays, reworded as the works-from-any-device check. Not started:
- * the plain smoke test to run after starting.
+ * Remote health-check block. Running or starting: the CLI verified localhost
+ * on the VPS (or the container is still coming up), but the public URL is a
+ * different check (ingress — DNS, TLS, proxy), so the command stays, reworded
+ * as the works-from-any-device check. Not started: the plain smoke test to
+ * run after starting.
  */
-const remoteHealthCheckBlock = (healthUrl, started) => {
-    if (started) {
+const remoteHealthCheckBlock = (healthUrl, startStatus) => {
+    if (startStatus === "running" || startStatus === "starting") {
         return `Health check — works from any device that can reach the URL:
   curl ${healthUrl}`;
     }
@@ -119,18 +124,20 @@ const updateGuidance = (targetDir) => `Update to the latest release:
  * actually run.
  */
 export const buildLocalConnectMessage = (params) => {
-    const { targetDir, token, started, port, tokenWritten } = params;
+    const { targetDir, token, startStatus, port, tokenWritten } = params;
     const baseUrl = `http://localhost:${port}`;
-    const startLine = started
+    const startLine = startStatus === "running"
         ? "The server is running."
-        : startServerLine(targetDir);
+        : startStatus === "starting"
+            ? startingInBackgroundLine()
+            : startServerLine(targetDir);
     const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
     // Once the server is confirmed up, the smoke test is dropped — the CLI just
     // verified this exact URL, so re-printing it reads as leftover homework.
     // Assembled as a filtered list so the omission leaves no stray blank line.
     const nonOauthBlocks = [
         curlGuidance(`${baseUrl}/mcp`),
-        started ? undefined : smokeTest(`${baseUrl}/healthz`),
+        startStatus === "running" ? undefined : smokeTest(`${baseUrl}/healthz`),
     ]
         .filter(Boolean)
         .join("\n\n");
@@ -187,10 +194,10 @@ ${bottomRule()}`;
  * handling here.
  */
 export const buildRemoteConnectMessage = (params) => {
-    const { targetDir, token, publicUrl, started, obsidianTokenMissing, tokenWritten, } = params;
+    const { targetDir, token, publicUrl, startStatus, obsidianTokenMissing, tokenWritten, } = params;
     const startLine = remoteStartLine({
         targetDir,
-        started,
+        startStatus,
         obsidianTokenMissing,
     });
     const tokenLine = tokenBlock({ targetDir, token, tokenWritten });
@@ -227,7 +234,7 @@ ${sectionRule("Non-OAuth")}
 
 ${curlGuidance(`${publicUrl}/mcp`)}
 
-${remoteHealthCheckBlock(`${publicUrl}/healthz`, started)}
+${remoteHealthCheckBlock(`${publicUrl}/healthz`, startStatus)}
 
 ${sectionRule("Settings")}
 

package/package.json

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