vault-cortex 0.7.0 → 0.9.0-beta.43

package/dist/lifecycle.js

@@ -0,0 +1,204 @@
+import { join, resolve } from "node:path";
+import { CONTAINER_NAME, 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";
+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.
+ */
+export 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@latest 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;
+    }
+    // Local's PUBLIC_URL is the derived localhost URL — probing it would
+    // duplicate the health check recreateContainer just ran, so remote-only.
+    const publicUrl = mode === "remote" ? readEnvPublicUrl(envFilePath) : undefined;
+    return { mode, targetDir, envFilePath, port, vaultPath, publicUrl };
+};
+/**
+ * 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) => {
+    const daemonStatus = docker.daemonStatus();
+    if (daemonStatus === "running")
+        return true;
+    prompts.error(daemonStatus === "not-installed"
+        ? buildDockerNotInstalledMessage({ nextStep: "" })
+        : buildDaemonNotRunningMessage("."));
+    return false;
+};
+/**
+ * One-shot informational probe of the public /healthz after a confirmed
+ * container start. Never a gate: a failure warns and the command still
+ * succeeds — before HTTPS/ingress access is set up an unreachable public URL
+ * is the expected state, and this machine's result doesn't prove the same
+ * for other devices (a VPS may not reach its own public address). Returning
+ * void keeps the informational contract structural.
+ */
+export const reportPublicUrlProbe = async (publicUrl, deps) => {
+    const { prompts, fetchFn } = deps;
+    // A hand-edited .env value may carry a trailing slash; strip it so the
+    // probe URL is `${base}/healthz`, never `${base}//healthz`.
+    const healthUrl = `${publicUrl.replace(/\/+$/, "")}/healthz`;
+    const spinner = prompts.spinner();
+    spinner.start(`Checking the public URL (${healthUrl})`);
+    const publicUrlResponded = await probeHealth({ url: healthUrl }, fetchFn);
+    if (publicUrlResponded) {
+        spinner.stop(`Public URL responds — ${healthUrl} answered from this machine.`);
+        return;
+    }
+    spinner.stop(`No answer from ${healthUrl} yet.`);
+    prompts.warn("The server is up, but its public URL didn't answer from this machine.\n" +
+        "That's expected until HTTPS (or direct port) access is set up — and\n" +
+        "some networks keep a server from reaching its own public address even\n" +
+        "when other devices can. Once access is set up, check from any device:\n" +
+        `  curl ${healthUrl}`);
+};
+/**
+ * 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.");
+    // Informational only — the container is confirmed healthy above, so the
+    // public-URL result never changes the exit code.
+    if (deployment.mode === "remote" && deployment.publicUrl) {
+        await reportPublicUrlProbe(deployment.publicUrl, { prompts, fetchFn });
+    }
+    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@latest 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@latest 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,8 @@
+import { runConfigure } from "./configure.js";
 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";
@@ -12,11 +14,29 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runConfigure: (flags) => runConfigure(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+            fetchFn: fetch,
+        }),
         runUpgrade: (flags) => runUpgrade(flags, {
             prompts: createPrompts(),
             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

@@ -10,9 +10,41 @@ const RULE_WIDTH = 56;
 const topRule = (label) => paint("dim", `╭── ${label} ${"─".repeat(Math.max(0, RULE_WIDTH - label.length - 6))}╮`);
 const bottomRule = () => paint("dim", `╰${"─".repeat(RULE_WIDTH - 2)}╯`);
 const sectionRule = (label) => paint("dim", `── ${label} ${"─".repeat(Math.max(0, RULE_WIDTH - label.length - 4))}`);
+/**
+ * Daemon-stopped guidance shared by every command that needs the container
+ * runtime. `nextStep` finishes the message per command — appended verbatim
+ * (".", " and try again.", or a ", then run:" continuation).
+ */
+export const buildDaemonNotRunningMessage = (nextStep) => "Container runtime not running — start Docker Desktop, Colima,\n" +
+    `OrbStack, or another Docker-compatible runtime${nextStep}`;
+/**
+ * Per-platform install pointer — a docs link only, no install method
+ * suggestions: the CLI doesn't install anything, so the official docs (which
+ * cover every method) are the hand-off. Peers are named in the message above
+ * this line.
+ */
+const dockerInstallLine = (platform) => {
+    if (platform === "darwin" || platform === "win32") {
+        return "Install Docker Desktop: https://docs.docker.com/get-docker/";
+    }
+    return "Install Docker Engine: https://docs.docker.com/engine/install/";
+};
+/**
+ * "No runtime at all" guidance — distinct from the daemon-stopped message so
+ * the user isn't told to start something that isn't installed. platform is a
+ * defaulted param (mirroring buildObsidianLoginArgs) so each branch stays
+ * testable; `nextStep` is appended verbatim, as in
+ * buildDaemonNotRunningMessage.
+ */
+export const buildDockerNotInstalledMessage = (params) => {
+    const { nextStep, platform = process.platform } = params;
+    return ("No container runtime found — the server runs in Docker, so you need\n" +
+        "Docker or a Docker-compatible runtime (OrbStack, Colima, Podman).\n" +
+        `${dockerInstallLine(platform)}${nextStep}`);
+};
 // targetDir is quoted: these lines are meant to be copy-pasted into a
 // shell, and an unquoted path breaks on spaces or special characters.
-const upgradeCommand = (targetDir) => `npx vault-cortex upgrade --dir "${targetDir}"`;
+const upgradeCommand = (targetDir) => `npx vault-cortex@latest upgrade --dir "${targetDir}"`;
 const startServerLine = (targetDir) => `Start the server:\n  ${upgradeCommand(targetDir)}`;
 /** Remote start line: running, blocked on the missing sync token, or ready to start. */
 const remoteStartLine = (params) => {
@@ -62,6 +94,19 @@ const curlGuidance = (mcpUrl) => `Clients without OAuth, scripts, and curl send
   curl -H "Authorization: Bearer <token>" ${mcpUrl}`;
 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.
+ */
+const remoteHealthCheckBlock = (healthUrl, started) => {
+    if (started) {
+        return `Health check — works from any device that can reach the URL:
+  curl ${healthUrl}`;
+    }
+    return smokeTest(healthUrl);
+};
 const updateGuidance = (targetDir) => `Update to the latest release:
   ${upgradeCommand(targetDir)}`;
 /**
@@ -76,6 +121,15 @@ export const buildLocalConnectMessage = (params) => {
         ? "The server is running."
         : 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`),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
     // 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
@@ -104,15 +158,17 @@ it with mcp-remote:
 
 ${sectionRule("Non-OAuth")}
 
-${curlGuidance(`${baseUrl}/mcp`)}
-
-${smokeTest(`${baseUrl}/healthz`)}
+${nonOauthBlocks}
 
 ${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).
+Adjust optional settings (memory layer and folder, file tools,
+semantic search, port, timezone):
+  npx vault-cortex@latest configure --dir "${targetDir}"
+
+Or edit ${targetDir}/.env directly — change a value (uncommenting it
+first if needed), then apply with "npx vault-cortex@latest restart" (plain
+docker restart does not re-read .env).
 
 ${updateGuidance(targetDir)}
 
@@ -167,14 +223,17 @@ ${sectionRule("Non-OAuth")}
 
 ${curlGuidance(`${publicUrl}/mcp`)}
 
-${smokeTest(`${publicUrl}/healthz`)}
+${remoteHealthCheckBlock(`${publicUrl}/healthz`, started)}
 
 ${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).
+Adjust optional settings (memory layer and folder, file tools,
+semantic search, port, timezone, sync direction):
+  npx vault-cortex@latest configure --dir "${targetDir}"
+
+Or edit ${targetDir}/.env directly — change a value (uncommenting it
+first if needed), then apply with "npx vault-cortex@latest restart" (plain
+docker restart does not re-read .env).
 
 ${updateGuidance(targetDir)}
 

package/dist/optional-settings.js

@@ -0,0 +1,233 @@
+import { DEFAULT_PORT } from "./scaffold.js";
+// The curated prompt set — settings users most often want without reading
+// .env comments. Everything else stays documented-only in the generated
+// optional block, deliberately: every extra prompt costs init flow length.
+const OPTIONAL_SETTINGS = [
+    {
+        kind: "toggle",
+        name: "MEMORY_ENABLED",
+        label: "Memory layer",
+        question: "Enable the memory layer (About Me/ folder + memory tools)?",
+    },
+    {
+        kind: "folder",
+        name: "MEMORY_DIR",
+        label: "Memory folder",
+        question: "Vault folder for the memory files:",
+        defaultValue: "About Me",
+        requiresToggle: "MEMORY_ENABLED",
+    },
+    {
+        kind: "toggle",
+        name: "FILE_TOOLS_ENABLED",
+        label: "File tools",
+        question: "Enable file tools (read images, PDFs, and other non-Markdown files)?",
+    },
+    {
+        kind: "toggle",
+        name: "EMBEDDING_ENABLED",
+        label: "Semantic search",
+        question: "Enable semantic search embeddings (richer search, slower first startup)?",
+    },
+    { kind: "port", name: "PORT", label: "Host port" },
+    { kind: "timezone", name: "TZ", label: "Timezone" },
+    {
+        kind: "choice",
+        name: "SYNC_MODE",
+        label: "Sync direction",
+        question: "Obsidian Sync direction:",
+        choices: [
+            {
+                value: "bidirectional",
+                label: "Bidirectional",
+                hint: "pull remote changes and push server-side edits",
+            },
+            {
+                value: "pull-only",
+                label: "Pull-only",
+                hint: "receive changes but never push",
+            },
+            {
+                value: "push-only",
+                label: "Push-only",
+                hint: "push changes but never pull",
+            },
+        ],
+        defaultValue: "bidirectional",
+        remoteOnly: true,
+    },
+];
+/** Matches the full active (uncommented) assignment line for a var. */
+const activeLinePattern = (name) => new RegExp(`^${name}=.*$`, "m");
+/** Matches the full commented-out assignment line (`# VAR=...`) for a var. */
+const commentedLinePattern = (name) => new RegExp(`^# ${name}=.*$`, "m");
+/**
+ * Reads a var's current value from .env content. A commented-out or missing
+ * line returns undefined — both mean "the server uses its built-in default",
+ * which is exactly what the prompts need to distinguish. Duplicate lines
+ * report the LAST value, matching docker --env-file precedence — hints,
+ * prompt seeding, and the PUBLIC_URL derivation must reason from the value
+ * that actually takes effect.
+ */
+export const readOptionalValue = (envContent, name) => {
+    const matches = [...envContent.matchAll(new RegExp(`^${name}=(.*)$`, "gm"))];
+    return matches.at(-1)?.[1].trim();
+};
+/**
+ * Applies chosen values to .env content as a pure text transform: every
+ * active line for the var is replaced (docker --env-file gives the last
+ * duplicate precedence, so a single-line replace could leave a stale
+ * duplicate winning), a commented-out line is uncommented and replaced, and
+ * a var with no line at all (a .env predating the setting) is appended —
+ * the chosen value must land in the file, never be silently dropped.
+ */
+export const applyOptionalSettings = (envContent, overrides) => Object.entries(overrides).reduce((content, [name, value]) => {
+    // Fresh RegExp per use (the /g flag makes instances stateful via
+    // lastIndex); function replacements avoid $-pattern interpretation in
+    // values, same as patchEnvObsidianToken.
+    const everyActiveLine = new RegExp(`^${name}=.*$`, "gm");
+    if (activeLinePattern(name).test(content)) {
+        return content.replace(everyActiveLine, () => `${name}=${value}`);
+    }
+    if (commentedLinePattern(name).test(content)) {
+        return content.replace(commentedLinePattern(name), () => `${name}=${value}`);
+    }
+    return `${content.trimEnd()}\n\n${name}=${value}\n`;
+}, envContent);
+/**
+ * A PORT override moves the server, and the local quickstart derives
+ * PUBLIC_URL (the OAuth issuer) from that port. When the current PUBLIC_URL
+ * is exactly the derived http://localhost:<current port> form, it follows
+ * the new port — otherwise the advertised OAuth discovery endpoints would
+ * point at a port nothing listens on. A custom PUBLIC_URL (reverse proxy,
+ * remote domain) is the user's own and is never touched.
+ */
+export const derivePublicUrlOverride = (envContent, overrides) => {
+    const newPort = overrides.PORT;
+    if (!newPort)
+        return overrides;
+    const currentPort = readOptionalValue(envContent, "PORT") ?? String(DEFAULT_PORT);
+    const currentPublicUrl = readOptionalValue(envContent, "PUBLIC_URL");
+    if (currentPublicUrl !== `http://localhost:${currentPort}`)
+        return overrides;
+    return { ...overrides, PUBLIC_URL: `http://localhost:${newPort}` };
+};
+/**
+ * The .env spellings the server reads as "off" — env-var's asBool accepts
+ * 0/1 alongside true/false. An absent or unrecognized value falls to the
+ * server default, which is enabled for every curated toggle.
+ */
+const isDisabledToggleValue = (value) => ["false", "0"].includes((value ?? "").toLowerCase());
+/**
+ * Plain digits in the TCP port range. Number() coercion is not enough:
+ * it accepts "1e4"/"0x1F40"/"+9000", which readEnvPort's /^PORT=(\d+)/
+ * would later fail to read back — silently falling to the default port.
+ */
+const isValidPort = (value) => {
+    if (!/^\d+$/.test(value))
+        return false;
+    const port = Number(value);
+    return port >= 1 && port <= 65535;
+};
+/**
+ * The engine's own IANA zone validation: Intl.DateTimeFormat throws a
+ * RangeError for an unknown timeZone, so no hand-rolled zone list to drift.
+ */
+const isValidTimezone = (value) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Re-prompts until the answer is a valid port number. */
+const askPort = async (currentValue, prompts) => {
+    const answer = (await prompts.text("Host port for the server:", {
+        defaultValue: currentValue ?? String(DEFAULT_PORT),
+        placeholder: String(DEFAULT_PORT),
+    })).trim();
+    if (isValidPort(answer))
+        return answer;
+    prompts.error("PORT must be a whole number between 1 and 65535.");
+    return askPort(currentValue, prompts);
+};
+/** Re-prompts until the answer is a zone the runtime recognizes. */
+const askTimezone = async (currentValue, prompts) => {
+    const answer = (await prompts.text("Your IANA timezone:", {
+        defaultValue: currentValue,
+        placeholder: "America/New_York",
+    })).trim();
+    if (answer !== "" && isValidTimezone(answer))
+        return answer;
+    prompts.error(`"${answer}" is not a recognized IANA timezone (e.g. America/New_York, Europe/London).`);
+    return askTimezone(currentValue, prompts);
+};
+/** Re-prompts until the answer is a non-empty folder name. */
+const askFolder = async (params, prompts) => {
+    const { question, currentValue, defaultValue } = params;
+    const answer = (await prompts.text(question, {
+        defaultValue: currentValue ?? defaultValue,
+        placeholder: defaultValue,
+    })).trim();
+    if (answer !== "")
+        return answer;
+    prompts.error("The folder name can't be empty.");
+    return askFolder(params, prompts);
+};
+/** Routes a picked setting to its kind's prompt and returns the .env value. */
+const askSettingValue = async (params, prompts) => {
+    const { setting, currentValue } = params;
+    switch (setting.kind) {
+        case "toggle": {
+            const enabled = await prompts.confirm(setting.question, !isDisabledToggleValue(currentValue));
+            return String(enabled);
+        }
+        case "port":
+            return askPort(currentValue, prompts);
+        case "timezone":
+            return askTimezone(currentValue, prompts);
+        case "folder":
+            return askFolder({
+                question: setting.question,
+                currentValue,
+                defaultValue: setting.defaultValue,
+            }, prompts);
+        case "choice":
+            return prompts.select(setting.question, setting.choices, currentValue ?? setting.defaultValue);
+    }
+};
+/**
+ * The guided optional-settings flow shared by init and configure: one
+ * multiselect chooser (enter with nothing picked = change nothing), then one
+ * prompt per picked setting. Returns the chosen values keyed by var name —
+ * the caller owns applying them via applyOptionalSettings.
+ */
+export const askOptionalSettings = async (params, prompts) => {
+    const { mode, envContent } = params;
+    const offeredSettings = OPTIONAL_SETTINGS.filter((setting) => !setting.remoteOnly || mode === "remote");
+    const chooserOptions = offeredSettings.map((setting) => {
+        const currentValue = readOptionalValue(envContent, setting.name);
+        const requiredToggle = OPTIONAL_SETTINGS.find((candidate) => candidate.name === setting.requiresToggle);
+        const dependencyNote = requiredToggle &&
+            isDisabledToggleValue(readOptionalValue(envContent, requiredToggle.name))
+            ? ` · not used while ${requiredToggle.label} is off`
+            : "";
+        return {
+            value: setting.name,
+            label: setting.label,
+            hint: `${setting.name} · currently ${currentValue || "not set"}${dependencyNote}`,
+        };
+    });
+    const pickedNames = await prompts.multiselect("Any optional settings to change? (press enter to skip)", chooserOptions);
+    // Sequential prompting: answers are gathered one at a time in the curated
+    // order, so the record builds up inside an honest loop.
+    const overrides = {};
+    for (const setting of offeredSettings) {
+        if (!pickedNames.includes(setting.name))
+            continue;
+        overrides[setting.name] = await askSettingValue({ setting, currentValue: readOptionalValue(envContent, setting.name) }, prompts);
+    }
+    return overrides;
+};

package/dist/program.js

@@ -15,6 +15,13 @@ export const buildProgram = (options) => {
         .action(async (flags) => {
         process.exitCode = await options.runInit(flags);
     });
+    program
+        .command("configure")
+        .description("Change optional settings interactively and restart to apply them")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .action(async (flags) => {
+        process.exitCode = await options.runConfigure(flags);
+    });
     program
         .command("upgrade")
         .description("Pull the latest image, re-create the container, and verify health")
@@ -22,6 +29,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/prompts.js

@@ -28,6 +28,9 @@ export const createPrompts = () => ({
     warn: (message) => clack.log.warn(message),
     error: (message) => clack.log.error(message),
     select: async (message, options, initialValue) => exitOnCancel(await clack.select({ message, options, initialValue })),
+    // required: false makes an empty submission legal — the Prompts contract
+    // promises "no picks" resolves to [] instead of a re-prompt loop.
+    multiselect: async (message, options) => exitOnCancel(await clack.multiselect({ message, options, required: false })),
     text: async (message, options = {}) => exitOnCancel(await clack.text({
         message,
         placeholder: options.placeholder,