@zokizuan/satori-cli 0.1.1 → 0.3.0

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.1.1 install --client codex
-npx -y @zokizuan/satori-cli@0.1.1 install --client claude
-npx -y @zokizuan/satori-cli@0.1.1 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.1.1 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.0 install --client codex
+npx -y @zokizuan/satori-cli@0.3.0 install --client claude
+npx -y @zokizuan/satori-cli@0.3.0 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.3.0 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.0 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.4.1"]
+args = ["-y", "@zokizuan/satori-mcp@4.9.0"]
 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/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/dist/package-installability.js

@@ -54,7 +54,7 @@ function assertPublishedVersion(packageName, version, ownerPackageName, ownerPac
             stdio: ["ignore", "pipe", "pipe"],
         });
     }
-    catch (error) {
+    catch {
         if (relation === "self") {
             throw new CliError("E_USAGE", `Cannot install ${ownerPackageName}@${ownerPackageVersion} because that package version is not published on npm. Publish ${ownerPackageName}@${ownerPackageVersion} first or use a local dev server config instead.`, 2);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "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.4.1"
+    "@zokizuan/satori-mcp": "4.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",