@zokizuan/satori-cli 0.1.1

package/dist/args.js

@@ -0,0 +1,474 @@
+import fs from "node:fs";
+import { CliError } from "./errors.js";
+const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
+const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
+function parsePositiveInteger(value, flagName) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new CliError("E_USAGE", `${flagName} must be a positive integer.`, 2);
+    }
+    return parsed;
+}
+function normalizeFlagToken(token) {
+    return token.replace(/^--/, "").replace(/-/g, "_");
+}
+function stripFlagPrefix(token) {
+    if (!token.startsWith("--")) {
+        throw new CliError("E_USAGE", `Expected a flag but found '${token}'.`, 2);
+    }
+    return token.slice(2);
+}
+function parseGlobalOptions(argv) {
+    const globals = {
+        startupTimeoutMs: 180000,
+        callTimeoutMs: 600000,
+        format: "json",
+        debug: false,
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        switch (token) {
+            case "--startup-timeout-ms": {
+                const next = argv[i + 1];
+                if (!next) {
+                    throw new CliError("E_USAGE", "Missing value for --startup-timeout-ms.", 2);
+                }
+                globals.startupTimeoutMs = parsePositiveInteger(next, "--startup-timeout-ms");
+                i += 2;
+                break;
+            }
+            case "--call-timeout-ms": {
+                const next = argv[i + 1];
+                if (!next) {
+                    throw new CliError("E_USAGE", "Missing value for --call-timeout-ms.", 2);
+                }
+                globals.callTimeoutMs = parsePositiveInteger(next, "--call-timeout-ms");
+                i += 2;
+                break;
+            }
+            case "--format": {
+                const next = argv[i + 1];
+                if (!next || (next !== "json" && next !== "text")) {
+                    throw new CliError("E_USAGE", "--format must be one of: json, text.", 2);
+                }
+                globals.format = next;
+                i += 2;
+                break;
+            }
+            case "--debug": {
+                globals.debug = true;
+                i += 1;
+                break;
+            }
+            default: {
+                return {
+                    globals,
+                    rest: argv.slice(i),
+                };
+            }
+        }
+    }
+    return { globals, rest: [] };
+}
+function parseRawArgsMode(args) {
+    let rawArgsMode = { kind: "none" };
+    const remaining = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--args-json") {
+            if (rawArgsMode.kind !== "none") {
+                throw new CliError("E_USAGE", "Use only one of --args-json or --args-file.", 2);
+            }
+            const next = args[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", "Missing value for --args-json.", 2);
+            }
+            rawArgsMode = next === "@-"
+                ? { kind: "stdin-json" }
+                : { kind: "json", value: next };
+            i += 1;
+            continue;
+        }
+        if (token === "--args-file") {
+            if (rawArgsMode.kind !== "none") {
+                throw new CliError("E_USAGE", "Use only one of --args-json or --args-file.", 2);
+            }
+            const next = args[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", "Missing value for --args-file.", 2);
+            }
+            rawArgsMode = { kind: "file", path: next };
+            i += 1;
+            continue;
+        }
+        remaining.push(token);
+    }
+    if (rawArgsMode.kind !== "none" && remaining.length > 0) {
+        throw new CliError("E_USAGE", "Tool argument flags cannot be combined with --args-json/--args-file.", 2);
+    }
+    return { rawArgsMode, remaining };
+}
+function parseInstallCommand(kind, args) {
+    let client = "all";
+    let dryRun = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--client") {
+            const next = args[i + 1];
+            if (next !== "all" && next !== "claude" && next !== "codex") {
+                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex.", 2);
+            }
+            client = next;
+            i += 1;
+            continue;
+        }
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        throw new CliError("E_USAGE", `Unknown arguments for ${kind}: ${args.slice(i).join(" ")}`, 2);
+    }
+    return { kind, client, dryRun };
+}
+export function parseCliArgs(argv) {
+    const { globals, rest } = parseGlobalOptions(argv);
+    if (rest.length === 0 || rest[0] === "help" || rest.includes("--help") || rest.includes("-h")) {
+        return {
+            globals,
+            command: { kind: "help" }
+        };
+    }
+    if (rest[0] === "version" || rest.includes("--version") || rest.includes("-v")) {
+        return {
+            globals,
+            command: { kind: "version" }
+        };
+    }
+    if (rest[0] === "install") {
+        return {
+            globals,
+            command: parseInstallCommand("install", rest.slice(1))
+        };
+    }
+    if (rest[0] === "uninstall") {
+        return {
+            globals,
+            command: parseInstallCommand("uninstall", rest.slice(1))
+        };
+    }
+    if (rest[0] === "tools") {
+        if (rest.length === 2 && rest[1] === "list") {
+            return {
+                globals,
+                command: { kind: "tools-list" }
+            };
+        }
+        throw new CliError("E_USAGE", "Unsupported tools subcommand. Use: tools list", 2);
+    }
+    if (rest[0] === "tool") {
+        if (rest[1] !== "call") {
+            throw new CliError("E_USAGE", "Unsupported tool subcommand. Use: tool call <toolName>", 2);
+        }
+        const toolName = rest[2];
+        if (!toolName) {
+            throw new CliError("E_USAGE", "Missing tool name. Use: tool call <toolName>", 2);
+        }
+        const { rawArgsMode, remaining } = parseRawArgsMode(rest.slice(3));
+        if (remaining.length > 0) {
+            throw new CliError("E_USAGE", `Unknown arguments for tool call: ${remaining.join(" ")}`, 2);
+        }
+        return {
+            globals,
+            command: {
+                kind: "tool-call",
+                toolName,
+                rawArgsMode
+            }
+        };
+    }
+    if (RESERVED_SUBCOMMANDS.has(rest[0])) {
+        throw new CliError("E_USAGE", `Unsupported command '${rest[0]}'.`, 2);
+    }
+    const toolName = rest[0];
+    const { rawArgsMode, remaining } = parseRawArgsMode(rest.slice(1));
+    return {
+        globals,
+        command: {
+            kind: "wrapper",
+            toolName,
+            rawArgsMode,
+            wrapperArgs: remaining
+        }
+    };
+}
+function readStdin(stdin, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            reject(new CliError("E_USAGE", "Timed out while reading stdin JSON for --args-json @-.", 2));
+        }, timeoutMs);
+        timeout.unref();
+        stdin.setEncoding("utf8");
+        stdin.on("data", (chunk) => {
+            chunks.push(String(chunk));
+        });
+        stdin.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            reject(new CliError("E_USAGE", `Failed to read stdin: ${error.message}`, 2));
+        });
+        stdin.on("end", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve(chunks.join(""));
+        });
+        stdin.resume();
+    });
+}
+function parseJsonObject(value, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("E_USAGE", `Invalid JSON from ${source}: ${message}`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("E_USAGE", `JSON from ${source} must be an object.`, 2);
+    }
+    return parsed;
+}
+export async function resolveRawArguments(rawArgsMode, options) {
+    switch (rawArgsMode.kind) {
+        case "none":
+            return {};
+        case "json":
+            return parseJsonObject(rawArgsMode.value, "--args-json");
+        case "file": {
+            if (!fs.existsSync(rawArgsMode.path)) {
+                throw new CliError("E_USAGE", `Arguments file not found: ${rawArgsMode.path}`, 2);
+            }
+            const content = fs.readFileSync(rawArgsMode.path, "utf8");
+            return parseJsonObject(content, "--args-file");
+        }
+        case "stdin-json": {
+            const text = await readStdin(options.stdin || process.stdin, options.stdinTimeoutMs);
+            if (text.trim().length === 0) {
+                throw new CliError("E_USAGE", "stdin was empty for --args-json @-.", 2);
+            }
+            return parseJsonObject(text, "--args-json @-");
+        }
+        default:
+            return {};
+    }
+}
+function isPrimitiveEnum(enumValues) {
+    return enumValues.every((value) => {
+        const valueType = typeof value;
+        return valueType === "string" || valueType === "number" || valueType === "boolean";
+    });
+}
+function unsupportedSchemaReason(schema) {
+    if (!schema || typeof schema !== "object") {
+        return "schema is not an object";
+    }
+    if ("oneOf" in schema) {
+        return "oneOf is not supported in wrapper mode";
+    }
+    if ("anyOf" in schema) {
+        return "anyOf is not supported in wrapper mode";
+    }
+    if ("allOf" in schema) {
+        return "allOf is not supported in wrapper mode";
+    }
+    if ("$ref" in schema) {
+        return "$ref is not supported in wrapper mode";
+    }
+    if ("patternProperties" in schema) {
+        return "patternProperties is not supported in wrapper mode";
+    }
+    if (Array.isArray(schema.enum) && !isPrimitiveEnum(schema.enum)) {
+        return "enum values must be primitive";
+    }
+    if (schema.type === "array") {
+        const itemSchema = schema.items;
+        if (!itemSchema || typeof itemSchema !== "object") {
+            return "array items schema is missing";
+        }
+        const itemReason = unsupportedSchemaReason(itemSchema);
+        if (itemReason) {
+            return `array item schema unsupported: ${itemReason}`;
+        }
+        if (typeof itemSchema.type === "string" && !PRIMITIVE_TYPES.has(itemSchema.type) && !Array.isArray(itemSchema.enum)) {
+            return "array item type must be primitive";
+        }
+    }
+    if (typeof schema.type === "string" && schema.type !== "object" && !PRIMITIVE_TYPES.has(schema.type) && !Array.isArray(schema.enum)) {
+        return `schema type '${schema.type}' is not supported`;
+    }
+    return null;
+}
+function parseBooleanValue(value) {
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    throw new CliError("E_USAGE", `Invalid boolean value '${value}'. Use true or false.`, 2);
+}
+function parseEnumValue(raw, enumValues) {
+    for (const entry of enumValues) {
+        if (typeof entry === "string" && entry === raw) {
+            return entry;
+        }
+        if (typeof entry === "number" && Number(raw) === entry) {
+            return entry;
+        }
+        if (typeof entry === "boolean") {
+            if (raw === "true" && entry === true) {
+                return true;
+            }
+            if (raw === "false" && entry === false) {
+                return false;
+            }
+        }
+    }
+    throw new CliError("E_USAGE", `Value '${raw}' is not in enum [${enumValues.map(String).join(", ")}].`, 2);
+}
+function parsePrimitive(schema, raw) {
+    if (Array.isArray(schema.enum)) {
+        return parseEnumValue(raw, schema.enum);
+    }
+    switch (schema.type) {
+        case "string":
+            return raw;
+        case "number": {
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed)) {
+                throw new CliError("E_USAGE", `Value '${raw}' must be a finite number.`, 2);
+            }
+            return parsed;
+        }
+        case "integer": {
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed)) {
+                throw new CliError("E_USAGE", `Value '${raw}' must be an integer.`, 2);
+            }
+            return parsed;
+        }
+        case "boolean":
+            return parseBooleanValue(raw);
+        default:
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `Primitive parsing unsupported for schema type '${String(schema.type)}'. Use --args-json/--args-file.`, 2);
+    }
+}
+export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperArgs) {
+    if (!inputSchema || typeof inputSchema !== "object") {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema is missing or invalid. Use --args-json/--args-file.`, 2);
+    }
+    const schema = inputSchema;
+    const rootReason = unsupportedSchemaReason(schema);
+    if (rootReason) {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema unsupported (${rootReason}). Use --args-json/--args-file.`, 2);
+    }
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object") {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema has no object properties. Use --args-json/--args-file.`, 2);
+    }
+    const requiredProps = Array.isArray(schema.required)
+        ? schema.required.filter((entry) => typeof entry === "string")
+        : [];
+    const normalizedToCanonical = new Map();
+    const propertySchemas = new Map();
+    for (const [propertyName, propertySchema] of Object.entries(properties)) {
+        const unsupportedReason = unsupportedSchemaReason(propertySchema);
+        if (unsupportedReason) {
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${propertyName} uses unsupported schema (${unsupportedReason}). Use --args-json/--args-file.`, 2);
+        }
+        const normalized = normalizeFlagToken(`--${propertyName}`);
+        normalizedToCanonical.set(normalized, propertyName);
+        propertySchemas.set(propertyName, propertySchema);
+    }
+    const parsed = {};
+    for (let i = 0; i < wrapperArgs.length; i += 1) {
+        const token = wrapperArgs[i];
+        if (!token.startsWith("--")) {
+            throw new CliError("E_USAGE", `Unexpected positional argument '${token}'.`, 2);
+        }
+        const normalizedFlag = normalizeFlagToken(token);
+        const isJsonFlag = normalizedFlag.endsWith("_json");
+        const baseNormalized = isJsonFlag ? normalizedFlag.slice(0, -5) : normalizedFlag;
+        const canonicalName = normalizedToCanonical.get(baseNormalized);
+        if (!canonicalName) {
+            throw new CliError("E_USAGE", `Unknown flag '${token}' for tool '${toolName}'.`, 2);
+        }
+        const propertySchema = propertySchemas.get(canonicalName);
+        if (isJsonFlag) {
+            const next = wrapperArgs[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", `Missing JSON value for ${token}.`, 2);
+            }
+            parsed[canonicalName] = parseJsonObject(next, token);
+            i += 1;
+            continue;
+        }
+        if (propertySchema?.type === "object") {
+            throw new CliError("E_USAGE", `Flag '${token}' requires JSON input. Use --${stripFlagPrefix(token)}-json '<json>'.`, 2);
+        }
+        if (propertySchema?.type === "array") {
+            const next = wrapperArgs[i + 1];
+            if (!next || next.startsWith("--")) {
+                throw new CliError("E_USAGE", `Missing value for ${token}.`, 2);
+            }
+            const itemSchema = propertySchema.items;
+            const parsedValue = parsePrimitive(itemSchema, next);
+            const existing = parsed[canonicalName];
+            if (!Array.isArray(existing)) {
+                parsed[canonicalName] = [parsedValue];
+            }
+            else {
+                existing.push(parsedValue);
+            }
+            i += 1;
+            continue;
+        }
+        if (propertySchema?.type === "boolean") {
+            const next = wrapperArgs[i + 1];
+            if (!next || next.startsWith("--")) {
+                parsed[canonicalName] = true;
+            }
+            else {
+                parsed[canonicalName] = parseBooleanValue(next);
+                i += 1;
+            }
+            continue;
+        }
+        const next = wrapperArgs[i + 1];
+        if (!next || next.startsWith("--")) {
+            throw new CliError("E_USAGE", `Missing value for ${token}.`, 2);
+        }
+        parsed[canonicalName] = parsePrimitive(propertySchema, next);
+        i += 1;
+    }
+    for (const requiredProp of requiredProps) {
+        if (!(requiredProp in parsed)) {
+            throw new CliError("E_USAGE", `Missing required flag for '${toolName}': --${requiredProp}.`, 2);
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=args.js.map

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+interface SessionOptions {
+    command: string;
+    args: string[];
+    env: Record<string, string | undefined>;
+    cwd?: string;
+    startupTimeoutMs: number;
+    callTimeoutMs: number;
+    writeStderr: (text: string) => void;
+}
+export declare class CliMcpSession {
+    private readonly client;
+    private readonly transport;
+    private readonly callTimeoutMs;
+    private readonly writeStderr;
+    constructor(client: Client, transport: StdioClientTransport, callTimeoutMs: number, writeStderr: (text: string) => void);
+    listTools(): Promise<any>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    close(): Promise<void>;
+    logProtocolFailure(error: unknown): never;
+    wireStderr(): void;
+}
+export declare function connectCliMcpSession(options: SessionOptions): Promise<CliMcpSession>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,101 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CliError } from "./errors.js";
+function sanitizeEnv(env) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value === "string") {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+function createTimeout(promise, timeoutMs, token, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new CliError(token, message, 3));
+        }, timeoutMs);
+        timer.unref();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }).catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export class CliMcpSession {
+    constructor(client, transport, callTimeoutMs, writeStderr) {
+        this.client = client;
+        this.transport = transport;
+        this.callTimeoutMs = callTimeoutMs;
+        this.writeStderr = writeStderr;
+    }
+    async listTools() {
+        return createTimeout(this.client.listTools(), this.callTimeoutMs, "E_CALL_TIMEOUT", `Timed out after ${this.callTimeoutMs}ms while calling tools/list.`);
+    }
+    async callTool(name, args) {
+        return createTimeout(this.client.callTool({ name, arguments: args }), this.callTimeoutMs, "E_CALL_TIMEOUT", `Timed out after ${this.callTimeoutMs}ms while calling tools/call for '${name}'.`);
+    }
+    async close() {
+        const stderr = this.transport.stderr;
+        try {
+            await this.client.close();
+        }
+        catch {
+            // Best-effort close.
+        }
+        try {
+            await this.transport.close();
+        }
+        catch {
+            // Best-effort close.
+        }
+        stderr?.removeAllListeners("data");
+    }
+    logProtocolFailure(error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("E_PROTOCOL_FAILURE", message, 3);
+    }
+    wireStderr() {
+        const stderr = this.transport.stderr;
+        if (!stderr) {
+            return;
+        }
+        stderr.on("data", (chunk) => {
+            this.writeStderr(String(chunk));
+        });
+    }
+}
+export async function connectCliMcpSession(options) {
+    const transport = new StdioClientTransport({
+        command: options.command,
+        args: options.args,
+        env: sanitizeEnv(options.env),
+        cwd: options.cwd,
+        stderr: "pipe",
+    });
+    const client = new Client({
+        name: "satori-cli",
+        version: "1.1.1",
+    });
+    const session = new CliMcpSession(client, transport, options.callTimeoutMs, options.writeStderr);
+    session.wireStderr();
+    try {
+        await createTimeout(client.connect(transport), options.startupTimeoutMs, "E_STARTUP_TIMEOUT", `Timed out after ${options.startupTimeoutMs}ms while starting MCP server.`);
+        return session;
+    }
+    catch (error) {
+        await session.close();
+        if (error instanceof CliError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("E_PROTOCOL_FAILURE", message, 3);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class CliError extends Error {
+    readonly token: string;
+    readonly exitCode: number;
+    constructor(token: string, message: string, exitCode: number);
+}
+export declare function asCliError(error: unknown): CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class CliError extends Error {
+    constructor(token, message, exitCode) {
+        super(message);
+        this.name = "CliError";
+        this.token = token;
+        this.exitCode = exitCode;
+    }
+}
+export function asCliError(error) {
+    if (error instanceof CliError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new CliError("E_PROTOCOL_FAILURE", error.message, 3);
+    }
+    return new CliError("E_PROTOCOL_FAILURE", String(error), 3);
+}
+//# sourceMappingURL=errors.js.map

package/dist/format.d.ts

@@ -0,0 +1,15 @@
+export interface CliWriters {
+    writeStdout: (text: string) => void;
+    writeStderr: (text: string) => void;
+}
+export interface StructuredEnvelopeSummary {
+    status: string;
+    reason?: string;
+    hintStatus?: unknown;
+}
+export type ManageStatusState = "indexing" | "indexed" | "indexfailed" | "requires_reindex" | "not_indexed" | "unknown";
+export declare function emitJson(writers: CliWriters, payload: unknown): void;
+export declare function emitError(writers: CliWriters, token: string, message: string): void;
+export declare function parseStructuredEnvelope(result: unknown): StructuredEnvelopeSummary | null;
+export declare function inferManageStatusState(result: unknown): ManageStatusState;
+//# sourceMappingURL=format.d.ts.map