@zokizuan/satori-cli 0.2.0 → 0.3.1

package/README.md

@@ -14,10 +14,11 @@ Shell CLI for Satori installation, skill packaging, and direct tool invocation w
 ## Install / Uninstall
 
 ```bash
-npx -y @zokizuan/satori-cli@0.2.0 install --client codex
-npx -y @zokizuan/satori-cli@0.2.0 install --client claude
-npx -y @zokizuan/satori-cli@0.2.0 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.2.0 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.1 install --client codex
+npx -y @zokizuan/satori-cli@0.3.1 install --client claude
+npx -y @zokizuan/satori-cli@0.3.1 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.3.1 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.1 doctor
 ```
 
 Managed install writes MCP config that launches:
@@ -25,13 +26,14 @@ Managed install writes MCP config that launches:
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.8.0"]
+args = ["-y", "@zokizuan/satori-mcp@4.9.1"]
 startup_timeout_ms = 180000
 ```
 
 ## Commands
 
 ```bash
+satori-cli doctor
 satori-cli tools list
 satori-cli tool call <toolName> --args-json '{"path":"/abs/repo","query":"auth"}'
 satori-cli tool call <toolName> --args-file ./args.json
@@ -41,6 +43,8 @@ satori-cli <toolName> [schema-subset flags]
 
 Global flags (`--startup-timeout-ms`, `--call-timeout-ms`, `--format`, `--debug`) must appear before the command token.
 
+`doctor` checks local setup without starting an MCP client: Node version, npm package visibility, provider env, and Milvus env.
+
 ## Development
 
 ```bash

package/assets/skills/satori-indexing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: satori-indexing
-description: Index lifecycle and remediation for Satori. Use when codebases are not indexed, stale, blocked, or need freshness recovery.
+description: Use when Satori codebases are not indexed, stale, blocked, still indexing, or need lifecycle recovery.
 ---
 
 # Satori Indexing
@@ -27,10 +27,12 @@ Use only:
 - Never call `manage_index(action="clear")` unless the user explicitly requests destructive reset.
 - Treat ignore-only churn as a `sync` problem first.
 - Respect blocked and indexing states instead of forcing retries blindly.
+- Use `status` and `list_codebases` freely; provider credentials are only needed for provider-backed lifecycle actions.
 
 ## Status Handling
 
 - `requires_reindex`: run `manage_index(action="reindex")`.
 - `not_ready` with indexing reason: check status and wait for terminal completion.
 - `not_indexed`: create the index.
+- `MISSING_PROVIDER_CONFIG`: run `satori-cli doctor` when available, then set missing provider or Milvus env before retrying create/reindex/sync/search.
 - Ignore-rule noise mitigation: update `.satoriignore`, wait debounce, and run `sync` for immediate convergence.

package/assets/skills/satori-navigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: satori-navigation
-description: Deterministic symbol navigation with Satori. Use after search results are found to lock exact spans and inspect call relationships.
+description: Use when search has returned candidate code and exact spans, symbol reads, or call relationships are needed.
 ---
 
 # Satori Navigation
@@ -14,12 +14,14 @@ Use only:
 2. `call_graph`
 3. `read_file`
 
+For lifecycle remediation (`requires_reindex`, `not_indexed`, indexing waits), switch to `satori-indexing`.
+
 ## Workflow
 
 1. Use grouped `search_codebase` results as the starting point.
-2. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
-3. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
-4. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span.
+2. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span when exact identity is available.
+3. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
+4. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
 5. Use `read_file(path=..., open_symbol=...)` or deterministic line spans for the final read.
 
 ## Rules
@@ -28,9 +30,10 @@ Use only:
 - `open_symbol` must resolve deterministically. Do not guess on ambiguity.
 - `read_file(mode="annotated")` is preferred when outline metadata is useful.
 - Follow continuation hints when plain reads are truncated.
+- Other tools do not run search freshness; remediate stale index state before trusting navigation.
 
 ## Remediation
 
-- `requires_reindex`: reindex before retrying navigation.
-- `not_ready`: wait for indexing to finish.
+- `requires_reindex`: switch to `satori-indexing` and reindex before retrying navigation.
+- `not_ready` or `not_indexed`: switch to `satori-indexing`; wait or create before retrying navigation.
 - `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.

package/assets/skills/satori-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: satori-search
-description: Semantic-first code search with Satori. Use for intent-based code discovery before file reads or grep.
+description: Use when finding code by behavior, concept, or symbol before opening files or falling back to grep.
 ---
 
 # Satori Search
@@ -16,16 +16,17 @@ Use only:
 
 ## Workflow
 
-1. Check readiness with `manage_index(action="status", path=...)`.
+1. Check readiness with `manage_index(action="status", path=...)` when index state is unknown.
 2. If not indexed, use `manage_index(action="create", path=...)`.
 3. If `requires_reindex` appears, stop and use `manage_index(action="reindex", path=...)`, then retry.
-4. Search with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
+4. Search the user-requested path with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
 
 ## Search Rules
 
 - Start with natural-language intent, not filenames.
 - Default to `scope="runtime"`.
 - Use operators only when needed: `lang:`, `path:`, `-path:`, `must:`, `exclude:`.
+- Pass the user's requested path; if Satori resolves an indexed parent, follow returned `navigationFallback` exactly.
 - Treat warnings as usable-but-degraded results, not fatal errors.
 - Use `debug=true` only when ranking or filter explanations are required.
 
@@ -33,4 +34,6 @@ Use only:
 
 - `requires_reindex`: run `manage_index(action="reindex")`, not `sync`.
 - `not_ready` with indexing reason: wait or check `manage_index(action="status")`.
+- `not_indexed`: run `manage_index(action="create")` on the repository root or requested indexed root.
+- `MISSING_PROVIDER_CONFIG` is active only when it appears as the tool response `code` or `reason`. If it appears inside `search_codebase` results, it may just be matched code content.
 - Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.

package/dist/args.d.ts

@@ -19,6 +19,8 @@ export type ParsedCommand = {
     kind: "help";
 } | {
     kind: "version";
+} | {
+    kind: "doctor";
 } | {
     kind: "install";
     client: InstallClient;

package/dist/args.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import { CliError } from "./errors.js";
-const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
+const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "doctor", "install", "uninstall"]);
 const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
 function parsePositiveInteger(value, flagName) {
     const parsed = Number.parseInt(value, 10);
@@ -145,6 +145,15 @@ export function parseCliArgs(argv) {
             command: { kind: "version" }
         };
     }
+    if (rest[0] === "doctor") {
+        if (rest.length !== 1) {
+            throw new CliError("E_USAGE", `Unknown arguments for doctor: ${rest.slice(1).join(" ")}`, 2);
+        }
+        return {
+            globals,
+            command: { kind: "doctor" }
+        };
+    }
     if (rest[0] === "install") {
         return {
             globals,

package/dist/doctor.d.ts

@@ -0,0 +1,20 @@
+import { execFileSync } from "node:child_process";
+type CheckStatus = "ok" | "warning" | "error";
+export interface DoctorCheck {
+    name: string;
+    status: CheckStatus;
+    message: string;
+}
+export interface DoctorResult {
+    status: CheckStatus;
+    checks: DoctorCheck[];
+    nextSteps: string[];
+}
+export interface DoctorOptions {
+    env?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+    execFileSyncImpl?: typeof execFileSync;
+}
+export declare function runDoctor(options?: DoctorOptions): DoctorResult;
+export {};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+import { readManagedPackageJson, resolveManagedPackageSpecifier } from "./managed-package.js";
+function parseNodeMajor(version) {
+    const match = version.match(/^v?(\d+)/);
+    return match ? Number(match[1]) : 0;
+}
+function selectedProvider(env) {
+    return env.EMBEDDING_PROVIDER || "VoyageAI";
+}
+function requiredEmbeddingEnv(provider) {
+    switch (provider) {
+        case "OpenAI":
+            return "OPENAI_API_KEY";
+        case "VoyageAI":
+            return "VOYAGEAI_API_KEY";
+        case "Gemini":
+            return "GEMINI_API_KEY";
+        case "Ollama":
+            return null;
+        default:
+            return "VOYAGEAI_API_KEY";
+    }
+}
+function addCheck(checks, name, status, message) {
+    checks.push({ name, status, message });
+}
+function overallStatus(checks) {
+    if (checks.some((check) => check.status === "error")) {
+        return "error";
+    }
+    if (checks.some((check) => check.status === "warning")) {
+        return "warning";
+    }
+    return "ok";
+}
+export function runDoctor(options = {}) {
+    const env = options.env || process.env;
+    const nodeVersion = options.nodeVersion || process.version;
+    const execImpl = options.execFileSyncImpl || execFileSync;
+    const checks = [];
+    const nextSteps = [];
+    const nodeMajor = parseNodeMajor(nodeVersion);
+    if (nodeMajor >= 20) {
+        addCheck(checks, "node_version", "ok", `Node ${nodeVersion} satisfies >=20.`);
+    }
+    else {
+        addCheck(checks, "node_version", "error", `Node ${nodeVersion} is unsupported. Install Node.js 20 or newer.`);
+        nextSteps.push("Install Node.js 20 or newer.");
+    }
+    try {
+        const specifier = resolveManagedPackageSpecifier();
+        const pkg = readManagedPackageJson();
+        execImpl("npm", ["view", `${pkg.name}@${pkg.version}`, "version", "--json"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        addCheck(checks, "npm_package_access", "ok", `${specifier} is visible to npm.`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        addCheck(checks, "npm_package_access", "warning", `Could not verify npm package access: ${message}`);
+        nextSteps.push("Verify npm can access @zokizuan/satori-mcp from this machine.");
+    }
+    const provider = selectedProvider(env);
+    const requiredKey = requiredEmbeddingEnv(provider);
+    if (requiredKey && !env[requiredKey]) {
+        addCheck(checks, "embedding_provider_env", "error", `${provider} requires ${requiredKey}.`);
+        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.");
+    }
+    else {
+        addCheck(checks, "milvus_address", "ok", "MILVUS_ADDRESS is present.");
+    }
+    if (env.MILVUS_TOKEN) {
+        addCheck(checks, "milvus_token", "ok", "MILVUS_TOKEN is present.");
+    }
+    else {
+        addCheck(checks, "milvus_token", "ok", "MILVUS_TOKEN is not set; local/unauthenticated Milvus endpoints are supported.");
+    }
+    return {
+        status: overallStatus(checks),
+        checks,
+        nextSteps: [...new Set(nextSteps)],
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import type { DoctorResult } from "./doctor.js";
 interface RunCliOptions {
     writeStdout?: (text: string) => void;
     writeStderr?: (text: string) => void;
@@ -11,6 +12,9 @@ interface RunCliOptions {
     callTimeoutMs?: number;
     cwd?: string;
     installabilityVerifier?: () => string | Promise<string>;
+    doctorRunner?: (options: {
+        env: NodeJS.ProcessEnv;
+    }) => DoctorResult;
     connectSession?: (options: {
         command: string;
         args: string[];

package/dist/index.js

@@ -9,6 +9,7 @@ import { emitError, emitJson, inferManageStatusState, parseStructuredEnvelope }
 import { executeInstallCommand } from "./install.js";
 import { verifyManagedPackageInstallability } from "./package-installability.js";
 import { resolveServerEntryPath } from "./resolve-server-entry.js";
+import { runDoctor } from "./doctor.js";
 const MANAGE_INDEX_MIN_POLL_TIMEOUT_MS = 10 * 60 * 1000;
 function firstText(result) {
     const content = result?.content;
@@ -46,6 +47,7 @@ function buildHelpPayload() {
         commands: [
             "install [--client all|codex|claude] [--dry-run]",
             "uninstall [--client all|codex|claude] [--dry-run]",
+            "doctor",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
             "tool call <toolName> --args-file <path>",
@@ -195,6 +197,19 @@ export async function runCli(argv, options = {}) {
             }
             return 0;
         }
+        if (parsed.command.kind === "doctor") {
+            const result = (options.doctorRunner || ((doctorOptions) => runDoctor({ env: doctorOptions.env })))({
+                env: effectiveEnv,
+            });
+            emitJson(writers, result);
+            if (parsed.globals.format === "text") {
+                writers.writeStderr(`satori-cli doctor status=${result.status}.\n`);
+                for (const step of result.nextSteps) {
+                    writers.writeStderr(`next: ${step}\n`);
+                }
+            }
+            return result.status === "error" ? 1 : 0;
+        }
         if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
             if (parsed.command.kind === "install") {
                 await (options.installabilityVerifier || verifyManagedPackageInstallability)();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Shell CLI for Satori MCP installation and skill-based workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@zokizuan/satori-mcp": "4.8.0"
+    "@zokizuan/satori-mcp": "4.9.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",