@zokizuan/satori-cli 0.4.0 → 0.4.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ham-zax
+Copyright (c) 2026 Hamza (@ham-zax)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,14 +5,16 @@ Installer and shell client for Satori MCP. Use this package to configure support
 ## Quick Start
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.0 install --client all
-npx -y @zokizuan/satori-cli@0.4.0 doctor
+npx -y @zokizuan/satori-cli@0.4.2 install --client all
+npx -y @zokizuan/satori-cli@0.4.2 doctor
 ```
 
 Supported clients are `codex`, `claude`, `opencode`, and `all`.
 
 The installer performs package resolution once, stores the MCP server under `~/.satori/mcp-runtime/`, writes a stable launcher at `~/.satori/bin/satori-mcp.js`, and writes client-specific config that starts the launcher directly with Node. Resident MCP startup should not run `npx` or require a custom long startup timeout.
 
+Treat `~/.satori/` as installer-owned state. The public setup path is the installer command above, not manual copying of runtime cache paths into each harness.
+
 The installer only manages Satori-owned config and the first-party workflow skill:
 
 - `satori`
@@ -20,15 +22,44 @@ The installer only manages Satori-owned config and the first-party workflow skil
 ## Commands
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.0 install --client codex
-npx -y @zokizuan/satori-cli@0.4.0 install --client claude
-npx -y @zokizuan/satori-cli@0.4.0 install --client opencode
-npx -y @zokizuan/satori-cli@0.4.0 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.4.0 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.4.2 install --client codex
+npx -y @zokizuan/satori-cli@0.4.2 install --client claude
+npx -y @zokizuan/satori-cli@0.4.2 install --client opencode
+npx -y @zokizuan/satori-cli@0.4.2 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.4.2 uninstall --client codex
 ```
 
 `doctor` checks Node, package visibility, provider env, and Milvus env without starting an MCP client.
 
+Typical first run:
+
+```bash
+npx -y @zokizuan/satori-cli@0.4.2 install --client all
+npx -y @zokizuan/satori-cli@0.4.2 doctor
+# restart your MCP client
+```
+
+The installer writes launcher config only. Runtime provider settings are read when the MCP client starts.
+
+Supported client installs expose the Satori runtime variable names in the client config:
+
+- Codex writes active `env_vars` forwarding plus an optional commented `[mcp_servers.satori.env]` template in `~/.codex/config.toml`.
+- Claude Code writes `mcpServers.satori.env` in `~/.claude.json` with `${VAR:-}` pass-through values.
+- OpenCode writes `mcp.satori.environment` in `~/.config/opencode/opencode.json` with `{env:VAR}` pass-through values.
+
+If you want a client to store literal values, replace the generated pass-through value for that client. In Codex, uncomment or add this table outside the installer-managed launcher block so reinstalls keep your edits:
+
+```toml
+[mcp_servers.satori.env]
+EMBEDDING_PROVIDER = "VoyageAI"
+EMBEDDING_MODEL = "voyage-4-large"
+EMBEDDING_OUTPUT_DIMENSION = "1024"
+VOYAGEAI_API_KEY = "pa-..."
+VOYAGEAI_RERANKER_MODEL = "rerank-2.5"
+MILVUS_ADDRESS = "https://your-zilliz-endpoint"
+MILVUS_TOKEN = "your-zilliz-token"
+```
+
 ## Direct Tool Calls
 
 ```bash

package/dist/doctor.js

@@ -7,6 +7,32 @@ function parseNodeMajor(version) {
 function selectedProvider(env) {
     return env.EMBEDDING_PROVIDER || "VoyageAI";
 }
+function defaultModelForProvider(provider) {
+    switch (provider) {
+        case "OpenAI":
+            return "text-embedding-3-small";
+        case "VoyageAI":
+            return "voyage-4-large";
+        case "Gemini":
+            return "gemini-embedding-001";
+        case "Ollama":
+            return "nomic-embed-text";
+        default:
+            return "voyage-4-large";
+    }
+}
+function selectedModel(env, provider) {
+    if (provider === "Ollama") {
+        return env.OLLAMA_MODEL || env.EMBEDDING_MODEL || defaultModelForProvider(provider);
+    }
+    return env.EMBEDDING_MODEL || defaultModelForProvider(provider);
+}
+function selectedDimension(env, provider) {
+    if (env.EMBEDDING_OUTPUT_DIMENSION) {
+        return env.EMBEDDING_OUTPUT_DIMENSION;
+    }
+    return provider === "VoyageAI" ? "1024" : "provider default";
+}
 function requiredEmbeddingEnv(provider) {
     switch (provider) {
         case "OpenAI":
@@ -62,17 +88,25 @@ export function runDoctor(options = {}) {
         nextSteps.push("Verify npm can access @zokizuan/satori-mcp from this machine.");
     }
     const provider = selectedProvider(env);
+    addCheck(checks, "embedding_provider", "ok", `Embedding provider: ${provider}.`);
+    addCheck(checks, "embedding_model", "ok", `Embedding model: ${selectedModel(env, provider)}.`);
+    addCheck(checks, "embedding_dimension", "ok", `Embedding output dimension: ${selectedDimension(env, provider)}.`);
     const requiredKey = requiredEmbeddingEnv(provider);
     if (requiredKey && !env[requiredKey]) {
         addCheck(checks, "embedding_provider_env", "error", `${provider} requires ${requiredKey}.`);
-        nextSteps.push(`Set ${requiredKey}.`);
+        if (provider === "VoyageAI") {
+            nextSteps.push("Set VOYAGEAI_API_KEY from the Voyage AI dashboard API keys page.");
+        }
+        else {
+            nextSteps.push(`Set ${requiredKey}.`);
+        }
     }
     else {
         addCheck(checks, "embedding_provider_env", "ok", requiredKey ? `${requiredKey} is present.` : `${provider} does not require an API key.`);
     }
     if (!env.MILVUS_ADDRESS) {
         addCheck(checks, "milvus_address", "error", "MILVUS_ADDRESS is required for index/search/clear operations.");
-        nextSteps.push("Set MILVUS_ADDRESS.");
+        nextSteps.push("Set MILVUS_ADDRESS to a Zilliz Cloud public endpoint or local Milvus address such as localhost:19530.");
     }
     else {
         addCheck(checks, "milvus_address", "ok", "MILVUS_ADDRESS is present.");
@@ -83,6 +117,9 @@ export function runDoctor(options = {}) {
     else {
         addCheck(checks, "milvus_token", "ok", "MILVUS_TOKEN is not set; local/unauthenticated Milvus endpoints are supported.");
     }
+    if (nextSteps.length > 0) {
+        nextSteps.push("Restart your MCP client after changing Satori environment variables.");
+    }
     return {
         status: overallStatus(checks),
         checks,

package/dist/install.js

@@ -8,12 +8,47 @@ import { CliError } from "./errors.js";
 import { resolveManagedPackageSpecifier } from "./managed-package.js";
 const MANAGED_BLOCK_START = "# >>> satori-cli managed satori start >>>";
 const MANAGED_BLOCK_END = "# <<< satori-cli managed satori end <<<";
+const CODEX_ENV_TEMPLATE_START = "# >>> satori-cli optional satori env template >>>";
+const CODEX_ENV_TEMPLATE_END = "# <<< satori-cli optional satori env template <<<";
 const INSTRUCTIONS_BLOCK_START = "<!-- satori-mcp:start -->";
 const INSTRUCTIONS_BLOCK_END = "<!-- satori-mcp:end -->";
 const OWNED_SKILL_DIRS = ["satori"];
 const MANAGED_RUNTIME_DIR = "mcp-runtime";
 const MANAGED_BIN_DIR = "bin";
 const MANAGED_LAUNCHER_FILE = "satori-mcp.js";
+const SATORI_RUNTIME_ENV_VARS = [
+    "EMBEDDING_PROVIDER",
+    "EMBEDDING_MODEL",
+    "EMBEDDING_OUTPUT_DIMENSION",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "VOYAGEAI_API_KEY",
+    "VOYAGEAI_RERANKER_MODEL",
+    "GEMINI_API_KEY",
+    "GEMINI_BASE_URL",
+    "OLLAMA_HOST",
+    "OLLAMA_MODEL",
+    "MILVUS_ADDRESS",
+    "MILVUS_TOKEN",
+    "READ_FILE_MAX_LINES",
+    "MCP_ENABLE_WATCHER",
+    "MCP_WATCH_DEBOUNCE_MS",
+];
+const CODEX_ENV_TEMPLATE_LINES = [
+    CODEX_ENV_TEMPLATE_START,
+    "# Optional direct Codex env values. Uncomment/fill these if you prefer",
+    "# ~/.codex/config.toml to store Satori runtime settings directly.",
+    "# This template is outside the launcher block so reinstall keeps edits.",
+    "# [mcp_servers.satori.env]",
+    "# EMBEDDING_PROVIDER = \"VoyageAI\"",
+    "# EMBEDDING_MODEL = \"voyage-4-large\"",
+    "# EMBEDDING_OUTPUT_DIMENSION = \"1024\"",
+    "# VOYAGEAI_API_KEY = \"pa-...\"",
+    "# VOYAGEAI_RERANKER_MODEL = \"rerank-2.5\"",
+    "# MILVUS_ADDRESS = \"https://your-zilliz-endpoint\"",
+    "# MILVUS_TOKEN = \"your-zilliz-token\"",
+    CODEX_ENV_TEMPLATE_END,
+];
 const OPENCODE_INSTRUCTIONS = `# Satori MCP
 
 This project uses Satori MCP for semantic code search, deterministic navigation, and index lifecycle management.
@@ -56,7 +91,7 @@ function resolveClientTargets(homeDir) {
         },
         {
             client: "claude",
-            configPath: path.join(homeDir, ".claude", "settings.json"),
+            configPath: path.join(homeDir, ".claude.json"),
             companion: {
                 kind: "skills",
                 path: path.join(homeDir, ".claude", "skills"),
@@ -103,6 +138,21 @@ function toTomlString(value) {
 function buildTomlArray(values) {
     return `[${values.map(toTomlString).join(", ")}]`;
 }
+function runtimeEnvMap(valueForName) {
+    return Object.fromEntries(SATORI_RUNTIME_ENV_VARS.map((name) => [name, valueForName(name)]));
+}
+function objectValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function mergeRuntimeEnv(existing, defaults) {
+    return {
+        ...defaults,
+        ...(objectValue(existing) ?? {}),
+    };
+}
 function packageNameFromSpecifier(packageSpecifier) {
     if (packageSpecifier.startsWith("@")) {
         const versionMarker = packageSpecifier.indexOf("@", 1);
@@ -258,10 +308,25 @@ function buildCodexManagedBlock(runtimeCommand) {
         "[mcp_servers.satori]",
         `command = ${toTomlString(runtimeCommand.command)}`,
         `args = ${buildTomlArray(runtimeCommand.args)}`,
+        "# Satori reads provider/vector settings from environment at MCP startup.",
+        "# env_vars forwards these names from Codex's parent environment when set.",
+        `env_vars = ${buildTomlArray([...SATORI_RUNTIME_ENV_VARS])}`,
         MANAGED_BLOCK_END,
         "",
     ].join("\n");
 }
+function buildCodexEnvTemplateBlock() {
+    return `${CODEX_ENV_TEMPLATE_LINES.join("\n")}\n`;
+}
+function codexHasSatoriEnvTable(content) {
+    return /^\s*\[mcp_servers\.satori\.env\]\s*$/m.test(content);
+}
+function ensureCodexEnvTemplate(content) {
+    if (content.includes(CODEX_ENV_TEMPLATE_START) || codexHasSatoriEnvTable(content)) {
+        return content;
+    }
+    return `${normalizeTrailingNewline(content)}\n${buildCodexEnvTemplateBlock()}`;
+}
 function codexHasUnmanagedSatoriSection(content) {
     if (!content.includes("[mcp_servers.satori]")) {
         return false;
@@ -284,6 +349,7 @@ function prepareCodexInstall(filePath, runtimeCommand) {
     else {
         next = `${normalizeTrailingNewline(current)}\n${managedBlock}`;
     }
+    next = ensureCodexEnvTemplate(next);
     return {
         changed: next !== current,
         apply: () => {
@@ -337,10 +403,12 @@ function parseJsonObject(filePath) {
     }
     return parsed;
 }
-function buildClaudeServerConfig(runtimeCommand) {
+function buildClaudeServerConfig(runtimeCommand, existing) {
     return {
+        type: "stdio",
         command: runtimeCommand.command,
         args: runtimeCommand.args,
+        env: mergeRuntimeEnv(existing?.env, runtimeEnvMap((name) => `\${${name}:-}`)),
     };
 }
 function isManagedLauncherPath(value) {
@@ -366,7 +434,8 @@ function isManagedClaudeEntry(value) {
 function prepareClaudeInstall(filePath, runtimeCommand) {
     const currentObject = parseJsonObject(filePath);
     const currentSerialized = JSON.stringify(currentObject);
-    const desiredServer = buildClaudeServerConfig(runtimeCommand);
+    const existingSatori = objectValue(currentObject.mcpServers?.satori);
+    const desiredServer = buildClaudeServerConfig(runtimeCommand, existingSatori);
     const mcpServersValue = currentObject.mcpServers;
     let mcpServers;
     if (mcpServersValue === undefined) {
@@ -378,8 +447,7 @@ function prepareClaudeInstall(filePath, runtimeCommand) {
     else {
         throw new CliError("E_USAGE", `Expected mcpServers to be an object in ${filePath}.`, 2);
     }
-    const existingSatori = mcpServers.satori;
-    if (existingSatori !== undefined && !isManagedClaudeEntry(existingSatori)) {
+    if (mcpServers.satori !== undefined && !isManagedClaudeEntry(mcpServers.satori)) {
         throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually or align it to the managed Satori form first.`, 2);
     }
     mcpServers.satori = {
@@ -439,11 +507,12 @@ function parseJsoncObject(filePath, content) {
     }
     return parsed;
 }
-function buildOpenCodeServerConfig(runtimeCommand) {
+function buildOpenCodeServerConfig(runtimeCommand, existing) {
     return {
         enabled: true,
         type: "local",
         command: [runtimeCommand.command, ...runtimeCommand.args],
+        environment: mergeRuntimeEnv(existing?.environment, runtimeEnvMap((name) => `{env:${name}}`)),
     };
 }
 function isManagedOpenCodeEntry(value) {
@@ -488,7 +557,7 @@ function prepareOpenCodeInstall(filePath, runtimeCommand) {
     if (existingSatori !== undefined && !isManagedOpenCodeEntry(existingSatori)) {
         throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcp.satori manually or align it to the managed Satori form first.`, 2);
     }
-    return mutateJsonc(filePath, current, ["mcp", "satori"], buildOpenCodeServerConfig(runtimeCommand));
+    return mutateJsonc(filePath, current, ["mcp", "satori"], buildOpenCodeServerConfig(runtimeCommand, objectValue(existingSatori)));
 }
 function prepareOpenCodeUninstall(filePath) {
     const current = readTextIfExists(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Shell CLI for Satori MCP installation and skill-based workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "jsonc-parser": "^3.3.1",
-    "@zokizuan/satori-mcp": "4.11.0"
+    "@zokizuan/satori-mcp": "4.11.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",