vault-cortex 0.7.0 → 0.8.0

package/README.md

@@ -23,6 +23,10 @@ manages the container so you don't have to.
   token, start the server
 - [`upgrade`](#upgrade) — pull the latest image and re-create the container;
   your data stays
+- [`restart`](#restart) — re-create the container so your `.env` edits take
+  effect; no image pull
+- [`logs`](#logs) — show the server's logs, live or after the fact
+- [`down`](#down) — stop and remove the container; your data stays
 - [`get-sync-token`](#get-sync-token) — generate an Obsidian Sync auth token
   for remote setups
 
@@ -88,6 +92,55 @@ include Compose files you can use directly. If you set up with Compose, stick
 with Compose for updates too (`docker compose pull && docker compose up -d`)
 — the CLI and Compose manage the container independently.
 
+## restart
+
+Re-create the container from your `.env` and verify health:
+
+```bash
+npx vault-cortex@latest restart
+```
+
+Use it after editing `.env` — settings are only read when the container is
+created, so a plain `docker restart` won't pick them up, but this will. Unlike
+[`upgrade`](#upgrade), it never pulls a new image: you get the same server
+version back, with your current settings applied.
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
+## logs
+
+Show the server's logs:
+
+```bash
+npx vault-cortex@latest logs
+```
+
+Flags:
+
+- `--follow` — keep streaming new output until you press ctrl-C
+- `--since <time>` — only logs newer than this (e.g. `10m`, `2h`, or a
+  timestamp)
+- `--dir <path>` — directory containing `.env` (default `./vault-cortex`)
+
+```bash
+npx vault-cortex@latest logs --follow --since 10m
+```
+
+## down
+
+Stop and remove the container:
+
+```bash
+npx vault-cortex@latest down
+```
+
+Safe by design: your vault, search index, and `.env` settings all live
+outside the container, so nothing is lost. Start again any time with
+[`restart`](#restart). Running `down` when nothing is running is fine — it
+just tells you there's nothing to stop.
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
 ## get-sync-token
 
 Generate an [Obsidian Sync](https://obsidian.md/sync) auth token — needed for

package/dist/docker.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 export const LOCAL_IMAGE = "ghcr.io/aliasunder/vault-cortex:latest";
 export const REMOTE_IMAGE = "ghcr.io/aliasunder/vault-cortex:remote";
 export const CONTAINER_NAME = "vault-cortex";
@@ -94,6 +94,19 @@ export const buildDockerRunArgs = (params) => {
     args.push(image);
     return args;
 };
+/**
+ * Builds the `docker logs` args array. Pure function — no I/O — so it's
+ * testable without spawning processes.
+ */
+export const buildDockerLogsArgs = (params) => {
+    const { follow, since } = params;
+    return [
+        "logs",
+        ...(follow ? ["--follow"] : []),
+        ...(since ? ["--since", since] : []),
+        CONTAINER_NAME,
+    ];
+};
 export const createDockerRunner = () => ({
     isDaemonRunning: () => spawnSync("docker", ["info"], { timeout: 5_000 }).status === 0,
     // stdout is discarded: `docker run -d` prints only the container ID there,
@@ -108,6 +121,33 @@ export const createDockerRunner = () => ({
     }).status === 0,
     pullImage: (image) => spawnSync("docker", ["pull", image], { stdio: "inherit" }).status === 0,
     stopAndRemoveContainer: () => spawnSync("docker", ["rm", "-f", CONTAINER_NAME]).status === 0,
+    // `docker rm -f` on a missing container exits 1 on engines < 23 and 0 on
+    // >= 23, so stopAndRemoveContainer's status can't distinguish "already
+    // gone" from "failed" — callers needing idempotent messaging probe
+    // existence first. Output stays piped (discarded): this is a boolean probe.
+    containerExists: () => spawnSync("docker", ["container", "inspect", CONTAINER_NAME]).status === 0,
+    // Async spawn, not spawnSync: --follow streams until interrupted, and the
+    // exit code must be observable after the stream closes.
+    streamLogs: (params) => new Promise((resolveExitCode) => {
+        const child = spawn("docker", buildDockerLogsArgs(params), {
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        // ctrl-C delivers SIGINT to the whole foreground process group. Node's
+        // default disposition would kill this process before the child's
+        // "close" event fires; this no-op keep-alive lets the docker child
+        // exit on its own SIGINT, the streams flush, and the exit code
+        // propagate. `once` self-removes, so later ctrl-Cs behave normally.
+        process.once("SIGINT", () => { });
+        child.once("error", (spawnError) => {
+            // Event handler, not a catch — but the same "never swallow" rule
+            // applies: without this line a spawn failure is a bare exit 1.
+            process.stderr.write(`vault-cortex: could not run docker logs — ${spawnError.message}\n`);
+            resolveExitCode(1);
+        });
+        // A null code means the child died to a signal — report the shell
+        // convention for ctrl-C (128 + SIGINT = 130).
+        child.once("close", (code) => resolveExitCode(code ?? 130));
+    }),
     runObsidianLogin: (configMountPath) => spawnSync("docker", buildObsidianLoginArgs({
         configMountPath,
         uid: process.getuid?.(),

package/dist/env.js

@@ -11,8 +11,8 @@
 // sync:local-optional:begin
 const LOCAL_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
 # To change a setting: edit its value (uncommenting it first if needed),
-# then apply with "npx vault-cortex upgrade" (restart alone does not
-# re-read this file).
+# then apply with "npx vault-cortex restart" (plain docker restart does
+# not re-read this file).
 
 # Public URL for OAuth issuer URL in discovery metadata (default: http://localhost:8000).
 # Override if you expose the server on a different URL (e.g. via a reverse proxy).
@@ -101,8 +101,8 @@ WINDOWS_MODE=false
 // sync:remote-optional:begin
 const REMOTE_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
 # To change a setting: edit its value (uncommenting it first if needed),
-# then apply with "npx vault-cortex upgrade" (restart alone does not
-# re-read this file).
+# then apply with "npx vault-cortex restart" (plain docker restart does
+# not re-read this file).
 
 # Your IANA timezone — affects daily note resolution and memory timestamps.
 # TZ=America/New_York
@@ -204,10 +204,6 @@ MCP_AUTH_TOKEN=${answers.mcpAuthToken}
 # Absolute path to your Obsidian vault on this machine.
 VAULT_PATH=${answers.vaultPath}
 
-# Public URL for OAuth issuer URL in discovery metadata.
-# Override if you expose the server on a different URL (e.g. via a reverse proxy).
-PUBLIC_URL=http://localhost:8000
-
 ${LOCAL_OPTIONAL_BLOCK}`;
 export const buildRemoteEnv = (answers) => {
     const vaultPasswordLines = answers.vaultPassword === undefined

package/dist/lifecycle.js

@@ -0,0 +1,166 @@
+import { join, resolve } from "node:path";
+import { CONTAINER_NAME, pollHealth } from "./docker.js";
+import { detectMode, hasEnvPublicUrl, readEnvPort, readEnvVaultPath, } from "./scaffold.js";
+import { expandTilde } from "./vault.js";
+const DEFAULT_TARGET_DIR = "./vault-cortex";
+/**
+ * Light gate for commands that operate on an existing deployment without
+ * starting a container: resolves --dir and confirms an init'd .env exists.
+ * Full start-readiness validation lives in resolveDeployment.
+ */
+const requireInitializedDir = (dirFlag, prompts) => {
+    const targetDir = resolve(expandTilde(dirFlag ?? DEFAULT_TARGET_DIR));
+    const envFilePath = join(targetDir, ".env");
+    const mode = detectMode(envFilePath);
+    if (!mode) {
+        prompts.error(`No .env found in ${targetDir} — run \`npx vault-cortex init\` first.`);
+        return undefined;
+    }
+    return { targetDir, envFilePath, mode };
+};
+/**
+ * Resolves --dir to the on-disk deployment and validates its .env for a
+ * container start: mode detection, VAULT_PATH (local), and PUBLIC_URL
+ * (local). Reports each failure via prompts.error and returns undefined.
+ * Shared by upgrade and restart so their precondition checks can't drift.
+ */
+export const resolveDeployment = (dirFlag, prompts) => {
+    const initialized = requireInitializedDir(dirFlag, prompts);
+    if (!initialized)
+        return undefined;
+    const { targetDir, envFilePath, mode } = initialized;
+    const port = readEnvPort(envFilePath);
+    const vaultPath = mode === "local" ? readEnvVaultPath(envFilePath) : undefined;
+    if (mode === "local" && !vaultPath) {
+        prompts.error(`VAULT_PATH is empty or missing in ${targetDir}/.env — cannot start the container.`);
+        return undefined;
+    }
+    if (mode === "local" && !hasEnvPublicUrl(envFilePath)) {
+        prompts.error(`PUBLIC_URL not found in ${targetDir}/.env — the server requires it.\n` +
+            `Add this line to your .env:\n  PUBLIC_URL=http://localhost:${port}`);
+        return undefined;
+    }
+    return { mode, targetDir, envFilePath, port, vaultPath };
+};
+/**
+ * Verifies the container runtime is reachable, reporting the shared error
+ * message when it isn't. Callers early-return on false.
+ */
+export const ensureDaemonRunning = (docker, prompts) => {
+    if (docker.isDaemonRunning())
+        return true;
+    prompts.error("Container runtime not running — start Docker Desktop, Colima,\n" +
+        "OrbStack, or another Docker-compatible runtime.");
+    return false;
+};
+/**
+ * Stop-and-remove → docker run → health poll, with the shared messaging.
+ * Returns a process exit code. Callers own the daemon check and any
+ * image-pull step.
+ */
+export const recreateContainer = async (params, deps) => {
+    const { deployment, healthTimeoutMs } = params;
+    const { prompts, docker, fetchFn } = deps;
+    // `docker rm -f` on a missing container exits non-zero on engines < 23,
+    // so the bare return value can't distinguish "nothing to remove" from a
+    // real failure — only treat removal as failed when a container exists.
+    // Proceeding after a genuine failure would surface as a confusing
+    // "container name already in use" from docker run.
+    if (docker.containerExists() && !docker.stopAndRemoveContainer()) {
+        prompts.error(`Could not remove the existing container — check: docker rm -f ${CONTAINER_NAME}`);
+        return 1;
+    }
+    prompts.log("Starting container...");
+    const containerStarted = docker.dockerRun({
+        mode: deployment.mode,
+        envFilePath: deployment.envFilePath,
+        port: deployment.port,
+        vaultPath: deployment.vaultPath,
+    });
+    if (!containerStarted) {
+        prompts.error("docker run failed — see output above.");
+        return 1;
+    }
+    const spinner = prompts.spinner();
+    spinner.start("Waiting for the server to come up");
+    const healthy = await pollHealth({
+        url: `http://127.0.0.1:${deployment.port}/healthz`,
+        timeoutMs: healthTimeoutMs,
+    }, fetchFn);
+    if (!healthy) {
+        spinner.stop(`Server did not respond within 2 minutes — check: docker logs ${CONTAINER_NAME}`);
+        return 1;
+    }
+    spinner.stop("Server is up — health check passed.");
+    return 0;
+};
+/**
+ * Stops and removes the container. Vault data, the search index, and .env
+ * settings all live outside the container (bind mount, named volumes, host
+ * file), so this is always safe.
+ */
+export const runDown = async (flags, deps) => {
+    const { prompts, docker } = deps;
+    prompts.intro("vault-cortex down");
+    // Teardown only needs to confirm this is an init'd directory — the full
+    // .env validation (VAULT_PATH, PUBLIC_URL) guards container starts.
+    const initialized = requireInitializedDir(flags.dir, prompts);
+    if (!initialized)
+        return 1;
+    if (!ensureDaemonRunning(docker, prompts))
+        return 1;
+    if (!docker.containerExists()) {
+        prompts.log("No vault-cortex container found — nothing to stop.");
+        prompts.outro("Done.");
+        return 0;
+    }
+    if (!docker.stopAndRemoveContainer()) {
+        prompts.error(`Could not remove the container — check: docker rm -f ${CONTAINER_NAME}`);
+        return 1;
+    }
+    prompts.log("Container stopped and removed. Your vault data, search index, and settings are untouched.");
+    prompts.outro(`Start again with: npx vault-cortex restart --dir "${initialized.targetDir}"`);
+    return 0;
+};
+/**
+ * Streams `docker logs` for the vault-cortex container. The stream's exit
+ * code passes through as the command's exit code; no outro follows the raw
+ * docker output.
+ */
+export const runLogs = async (flags, deps) => {
+    const { prompts, docker } = deps;
+    prompts.intro("vault-cortex logs");
+    const initialized = requireInitializedDir(flags.dir, prompts);
+    if (!initialized)
+        return 1;
+    if (!ensureDaemonRunning(docker, prompts))
+        return 1;
+    if (!docker.containerExists()) {
+        prompts.error("No vault-cortex container — start it with `npx vault-cortex restart`.");
+        return 1;
+    }
+    return await docker.streamLogs({
+        follow: Boolean(flags.follow),
+        since: flags.since,
+    });
+};
+/**
+ * Re-creates the container from the .env on disk and verifies health.
+ * Unlike `docker restart`, this applies .env edits (the env-file is only
+ * read at container creation); unlike upgrade, it never pulls an image.
+ */
+export const runRestart = async (flags, deps) => {
+    const { prompts, docker, fetchFn } = deps;
+    prompts.intro("vault-cortex restart");
+    const deployment = resolveDeployment(flags.dir, prompts);
+    if (!deployment)
+        return 1;
+    if (!ensureDaemonRunning(docker, prompts))
+        return 1;
+    const exitCode = await recreateContainer({ deployment, healthTimeoutMs: deps.healthTimeoutMs }, { prompts, docker, fetchFn });
+    if (exitCode !== 0)
+        return exitCode;
+    prompts.log("Applied the current .env settings.");
+    prompts.outro("Restart complete.");
+    return 0;
+};

package/dist/main.js

@@ -1,6 +1,7 @@
 import { createDockerRunner } from "./docker.js";
 import { runGetSyncToken } from "./get-sync-token.js";
 import { runInit } from "./init.js";
+import { runDown, runLogs, runRestart } from "./lifecycle.js";
 import { buildProgram } from "./program.js";
 import { createPrompts } from "./prompts.js";
 import { runUpgrade } from "./upgrade.js";
@@ -17,6 +18,19 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runRestart: (flags) => runRestart(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+            fetchFn: fetch,
+        }),
+        runLogs: (flags) => runLogs(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+        }),
+        runDown: (flags) => runDown(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+        }),
         runGetSyncToken: (flags) => runGetSyncToken(flags, {
             prompts: createPrompts(),
             docker: createDockerRunner(),

package/dist/messages.js

@@ -110,9 +110,10 @@ ${smokeTest(`${baseUrl}/healthz`)}
 
 ${sectionRule("Settings")}
 
-Optional settings (timezone, memory folder, port, logging) are commented
-out in ${targetDir}/.env — uncomment, set a value, then apply with
-"npx vault-cortex upgrade" (restart alone does not re-read .env).
+Optional settings (timezone, memory folder, port, logging) live in
+${targetDir}/.env — edit a value (uncommenting it first if needed), then
+apply with "npx vault-cortex restart" (plain docker restart does not
+re-read .env).
 
 ${updateGuidance(targetDir)}
 
@@ -172,9 +173,9 @@ ${smokeTest(`${publicUrl}/healthz`)}
 ${sectionRule("Settings")}
 
 Optional settings (timezone, memory folder, port, logging, sync
-behavior) are commented out in ${targetDir}/.env — uncomment, set a
-value, then apply with "npx vault-cortex upgrade" (restart alone does
-not re-read .env).
+behavior) live in ${targetDir}/.env — edit a value (uncommenting it
+first if needed), then apply with "npx vault-cortex restart" (plain
+docker restart does not re-read .env).
 
 ${updateGuidance(targetDir)}
 

package/dist/program.js

@@ -22,6 +22,29 @@ export const buildProgram = (options) => {
         .action(async (flags) => {
         process.exitCode = await options.runUpgrade(flags);
     });
+    program
+        .command("restart")
+        .description("Re-create the container from .env and verify health (applies .env edits; no image pull)")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .action(async (flags) => {
+        process.exitCode = await options.runRestart(flags);
+    });
+    program
+        .command("logs")
+        .description("Show container logs")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .option("--follow", "stream new log output until interrupted (ctrl-C)")
+        .option("--since <time>", 'only logs newer than this (e.g. "10m", "2h", or a timestamp)')
+        .action(async (flags) => {
+        process.exitCode = await options.runLogs(flags);
+    });
+    program
+        .command("down")
+        .description("Stop and remove the container — vault data and settings are preserved")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .action(async (flags) => {
+        process.exitCode = await options.runDown(flags);
+    });
     program
         .command("get-sync-token")
         .description("Generate an Obsidian Sync auth token via Docker and print it or write it to .env")

package/dist/upgrade.js

@@ -1,35 +1,19 @@
-import { join, resolve } from "node:path";
-import { CONTAINER_NAME, LOCAL_IMAGE, REMOTE_IMAGE, pollHealth, } from "./docker.js";
-import { detectMode, hasEnvPublicUrl, readEnvPort, readEnvVaultPath, } from "./scaffold.js";
-import { expandTilde } from "./vault.js";
-const DEFAULT_TARGET_DIR = "./vault-cortex";
+import { LOCAL_IMAGE, REMOTE_IMAGE } from "./docker.js";
+import { ensureDaemonRunning, recreateContainer, resolveDeployment, } from "./lifecycle.js";
+/**
+ * Pulls the latest image, re-creates the container, and verifies health.
+ * The only lifecycle command that contacts the registry — restart re-creates
+ * from the image already on disk.
+ */
 export const runUpgrade = async (flags, deps) => {
     const { prompts, docker, fetchFn } = deps;
     prompts.intro("vault-cortex upgrade");
-    const targetDir = resolve(expandTilde(flags.dir ?? DEFAULT_TARGET_DIR));
-    const envFilePath = join(targetDir, ".env");
-    const mode = detectMode(envFilePath);
-    if (!mode) {
-        prompts.error(`No .env found in ${targetDir} — run \`npx vault-cortex init\` first.`);
+    const deployment = resolveDeployment(flags.dir, prompts);
+    if (!deployment)
         return 1;
-    }
-    const port = readEnvPort(envFilePath);
-    const vaultPath = mode === "local" ? readEnvVaultPath(envFilePath) : undefined;
-    if (mode === "local" && !vaultPath) {
-        prompts.error(`VAULT_PATH is empty or missing in ${targetDir}/.env — cannot start the container.`);
-        return 1;
-    }
-    if (mode === "local" && !hasEnvPublicUrl(envFilePath)) {
-        prompts.error(`PUBLIC_URL not found in ${targetDir}/.env — the server requires it.\n` +
-            `Add this line to your .env:\n  PUBLIC_URL=http://localhost:${port}`);
-        return 1;
-    }
-    const image = mode === "local" ? LOCAL_IMAGE : REMOTE_IMAGE;
-    if (!docker.isDaemonRunning()) {
-        prompts.error("Container runtime not running — start Docker Desktop, Colima,\n" +
-            "OrbStack, or another Docker-compatible runtime.");
+    const image = deployment.mode === "local" ? LOCAL_IMAGE : REMOTE_IMAGE;
+    if (!ensureDaemonRunning(docker, prompts))
         return 1;
-    }
     const spinner = prompts.spinner();
     spinner.start(`Pulling ${image}`);
     const imagePulled = docker.pullImage(image);
@@ -38,28 +22,9 @@ export const runUpgrade = async (flags, deps) => {
         return 1;
     }
     spinner.stop("Image pulled.");
-    docker.stopAndRemoveContainer();
-    prompts.log("Starting container...");
-    const containerStarted = docker.dockerRun({
-        mode,
-        envFilePath,
-        port,
-        vaultPath,
-    });
-    if (!containerStarted) {
-        prompts.error("docker run failed — see output above.");
-        return 1;
-    }
-    spinner.start("Waiting for the server to come up");
-    const healthy = await pollHealth({
-        url: `http://127.0.0.1:${port}/healthz`,
-        timeoutMs: deps.healthTimeoutMs,
-    }, fetchFn);
-    if (!healthy) {
-        spinner.stop(`Server did not respond within 2 minutes — check: docker logs ${CONTAINER_NAME}`);
-        return 1;
-    }
-    spinner.stop("Server is up — health check passed.");
+    const exitCode = await recreateContainer({ deployment, healthTimeoutMs: deps.healthTimeoutMs }, { prompts, docker, fetchFn });
+    if (exitCode !== 0)
+        return exitCode;
     prompts.log("Your vault data, search index, and settings are preserved.");
     prompts.outro("Upgrade complete.");
     return 0;

package/package.json

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