@xmtp/convos-cli 0.1.0

package/dist/baseCommand.js

@@ -0,0 +1,171 @@
+/**
+ * Base command for Convos CLI.
+ *
+ * Provides:
+ *  - Common flags (--env, --json, --log-level, etc.)
+ *  - output() and streamOutput() helpers
+ *  - Config loading from .env files
+ *
+ * Convos adds: per-conversation identity resolution. Instead of a
+ * single wallet key, each conversation has its own identity with
+ * its own keys. Commands use getConvosConfig() + the identity store.
+ */
+import { env } from "node:process";
+import { createInterface } from "node:readline";
+import { Command, Errors, Flags } from "@oclif/core";
+import { formatHuman, isTTY, jsonStringify, VALID_ENVS, } from "./utils/xmtp.js";
+export class ConvosBaseCommand extends Command {
+    /** Flags shared by all commands. */
+    static commonFlags = {
+        "env-file": Flags.string({
+            description: "Path to .env file",
+            helpValue: "<path>",
+        }),
+        env: Flags.option({
+            options: [...VALID_ENVS],
+            description: "XMTP environment",
+        })(),
+        "gateway-host": Flags.string({
+            description: "Custom gateway URL",
+            helpValue: "<url>",
+        }),
+        json: Flags.boolean({
+            description: "Format output as JSON",
+        }),
+        verbose: Flags.boolean({
+            description: "Show additional diagnostic information",
+            default: false,
+        }),
+    };
+    /** Full flag set for commands that create a client. */
+    static baseFlags = {
+        ...ConvosBaseCommand.commonFlags,
+        "log-level": Flags.option({
+            options: ["off", "error", "warn", "info", "debug", "trace"],
+            description: "Logging level",
+        })(),
+        "structured-logging": Flags.boolean({
+            description: "Enable structured JSON logging",
+        }),
+        "app-version": Flags.string({
+            description: "App version string",
+            helpValue: "<version>",
+        }),
+    };
+    #config = {};
+    jsonOutput = false;
+    verbose = false;
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(this.constructor);
+        // Load config from .env file
+        // Priority: explicit --env-file > .env in cwd > ~/.convos/.env
+        const envFile = flags["env-file"];
+        if (envFile) {
+            try {
+                const { loadEnvFile } = await import("node:process");
+                const { resolve } = await import("node:path");
+                loadEnvFile(resolve(envFile));
+            }
+            catch (error) {
+                throw new Error(`Failed to load env file: ${envFile}`, {
+                    cause: error,
+                });
+            }
+        }
+        else {
+            const { loadEnvFile } = await import("node:process");
+            const { resolve, join } = await import("node:path");
+            const { homedir } = await import("node:os");
+            try {
+                loadEnvFile(resolve(process.cwd(), ".env"));
+            }
+            catch {
+                try {
+                    loadEnvFile(join(homedir(), ".convos", ".env"));
+                }
+                catch {
+                    // Silently ignore if neither file exists
+                }
+            }
+        }
+        // Merge env vars with CLI flags (CLI flags take precedence)
+        this.#config = {
+            env: flags.env ??
+                (VALID_ENVS.includes(env.CONVOS_ENV)
+                    ? env.CONVOS_ENV
+                    : undefined) ??
+                "dev",
+            logLevel: flags["log-level"] ?? env.XMTP_LOG_LEVEL,
+            structuredLogging: flags["structured-logging"] ??
+                (env.XMTP_STRUCTURED_LOGGING === "true" ? true : undefined),
+            gatewayHost: flags["gateway-host"] ?? env.XMTP_GATEWAY_HOST,
+            appVersion: flags["app-version"] ?? env.XMTP_APP_VERSION,
+            uploadProvider: env.CONVOS_UPLOAD_PROVIDER,
+            uploadProviderToken: env.CONVOS_UPLOAD_PROVIDER_TOKEN,
+            uploadProviderGateway: env.CONVOS_UPLOAD_PROVIDER_GATEWAY,
+        };
+        this.jsonOutput = flags.json || env.CONVOS_JSON_OUTPUT === "true";
+        this.verbose = flags.verbose || env.CONVOS_VERBOSE === "true";
+    }
+    output(data) {
+        if (this.jsonOutput) {
+            this.log(jsonStringify(data, true));
+        }
+        else {
+            this.log(formatHuman(data));
+        }
+    }
+    streamOutput(data) {
+        if (this.jsonOutput) {
+            this.log(jsonStringify(data));
+        }
+        else {
+            this.log(formatHuman(data));
+        }
+    }
+    parseBigInt(value, flagName) {
+        if (value === undefined)
+            return undefined;
+        try {
+            return BigInt(value);
+        }
+        catch {
+            this.error(`Invalid value for --${flagName}: must be a numeric string`);
+        }
+    }
+    async confirmAction(message, force) {
+        if (force)
+            return;
+        if (!isTTY()) {
+            this.error("Cannot confirm in non-interactive terminal. Use --force to skip confirmation.");
+        }
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        const answer = await new Promise((resolve) => {
+            rl.question(`WARNING: ${message}\nAre you sure? (y/N) `, resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+            this.error("Operation cancelled");
+        }
+    }
+    getConvosConfig() {
+        return this.#config;
+    }
+    async run() {
+        // Override in subclasses
+    }
+    catch(error) {
+        if (error instanceof Errors.CLIError) {
+            error.showHelp = false;
+            throw error;
+        }
+        const cliError = new Errors.CLIError(error.message);
+        cliError.showHelp = true;
+        cliError.parse = { input: { argv: this.argv } };
+        throw cliError;
+    }
+}

package/dist/commands/agent/serve.d.ts

@@ -0,0 +1,67 @@
+import { ConvosBaseCommand } from "../../baseCommand.js";
+export default class AgentServe extends ConvosBaseCommand {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        permissions: import("@oclif/core/interfaces").OptionFlag<"all-members" | "admin-only", import("@oclif/core/interfaces").CustomOptions>;
+        "profile-name": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        identity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "no-invite": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "log-level": import("@oclif/core/interfaces").OptionFlag<"off" | "error" | "warn" | "info" | "debug" | "trace" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "structured-logging": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "app-version": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "env-file": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<"local" | "dev" | "production" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "gateway-host": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private streams;
+    private shutdownResolve?;
+    /**
+     * Emit a JSON event to stdout (one line).
+     */
+    private emit;
+    /**
+     * Emit an error event.
+     */
+    private emitError;
+    /**
+     * Process a single DM message as a potential join request.
+     */
+    private processJoinMessage;
+    /**
+     * Process any pending DM join requests (batch, on startup).
+     */
+    private processPendingJoinRequests;
+    /**
+     * Start streaming DM messages for join request processing.
+     */
+    private startJoinRequestStream;
+    /**
+     * Start streaming conversation messages.
+     */
+    private startMessageStream;
+    /**
+     * Read and process stdin commands.
+     */
+    private startStdinReader;
+    /**
+     * Handle a parsed stdin command.
+     */
+    private handleCommand;
+    /**
+     * Trigger graceful shutdown.
+     */
+    private shutdown;
+    run(): Promise<void>;
+}