@marshell/cli 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @marshell/cli (Phase 0)
+
+Phase 0 command-line client for Marshell network bootstrap and local agent lifecycle.
+
+## Requirements
+
+- Node.js 20+
+- Bun (recommended) or npm
+
+## Install dependencies
+
+From `packages/cli`:
+
+```bash
+bun install
+```
+
+Or with npm:
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+Or:
+
+```bash
+npm run build
+```
+
+## Install (agents / production)
+
+```bash
+npm install -g https://marshell.dev/cli.tgz
+marshell auth set msk_...
+marshell agent join --name <short-name>
+```
+
+Default network: `https://network.marshell.dev`
+
+## Link globally (local dev)
+
+From `packages/cli` after build:
+
+```bash
+bun link
+```
+
+Then use:
+
+```bash
+marshell --help
+```
+
+npm alternative:
+
+```bash
+npm link
+```
+
+## Commands
+
+- `marshell auth set <token>`
+  - Saves join token to `~/.marshell/config.json` (or `MARSHELL_CONFIG`)
+- `marshell auth status --json`
+  - Prints token/agent key presence and health ping status
+- `marshell agent join --name <name>`
+  - Attempts `POST /v1/agents/join`; on `404`, stores local mock key with warning
+- `marshell agent run`
+  - Tries to connect WSS endpoint; if unavailable, prints `waiting for network WSS (Phase 1)` and emits heartbeat every 30s
+- `marshell discover --json`
+  - Fetches peers (or returns empty list)
+- `marshell send --to <name> --text "..." --json`
+  - Sends if endpoint exists; otherwise returns a Phase 1 stub warning
+- `marshell --help`
+
+## Environment variables
+
+- `MARSHELL_NETWORK_URL` (default: `http://localhost:8080`)
+- `MARSHELL_CONFIG` (optional absolute config path)
+
+## Notes
+
+- This package intentionally keeps protocol behavior light for Phase 0.
+- Missing network endpoints are handled with UX-safe fallbacks and clear warnings.

package/dist/cli.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const config_1 = require("./config");
+const network_1 = require("./network");
+function printHelp() {
+    const message = [
+        "marshell - Phase 0 CLI",
+        "",
+        "Usage:",
+        "  marshell auth set <token>",
+        "  marshell auth status [--json]",
+        "  marshell agent join --name <name>",
+        "  marshell agent run",
+        "  marshell discover [--json]",
+        "  marshell send --to <name> --text \"...\" [--json]",
+        "  marshell --help",
+        "",
+        "Environment:",
+        "  MARSHELL_NETWORK_URL  default: https://network.marshell.dev",
+        "  MARSHELL_CONFIG       optional path to config file",
+    ].join("\n");
+    process.stdout.write(`${message}\n`);
+}
+function printJson(payload) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function printError(message) {
+    process.stderr.write(`Error: ${message}\n`);
+    process.exit(1);
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function valueForFlag(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+async function cmdAuthSet(args) {
+    const token = args[0];
+    if (!token) {
+        printError("Usage: marshell auth set <token>");
+    }
+    await (0, config_1.patchConfig)({ token });
+    process.stdout.write(`Saved token to ${(0, config_1.getConfigPath)()}\n`);
+}
+async function cmdAuthStatus(args) {
+    const json = hasFlag(args, "--json");
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const health = await (0, network_1.pingNetwork)(networkUrl);
+    const payload = {
+        hasToken: Boolean(config.token),
+        hasAgentKey: Boolean(config.agentKey),
+        networkUrl,
+        health,
+    };
+    if (json) {
+        printJson(payload);
+        return;
+    }
+    process.stdout.write(`Token: ${payload.hasToken ? "present" : "missing"}\n`);
+    process.stdout.write(`Agent key: ${payload.hasAgentKey ? "present" : "missing"}\n`);
+    process.stdout.write(`Network health: ${health.ok ? "ok" : `down (${health.message ?? "unknown"})`}\n`);
+}
+async function cmdAgentJoin(args) {
+    const name = valueForFlag(args, "--name");
+    if (!name) {
+        printError("Usage: marshell agent join --name <name>");
+    }
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.joinAgent)(networkUrl, name);
+    if (result.kind === "joined") {
+        await (0, config_1.patchConfig)({ agentKey: result.agentKey, agentName: name });
+        process.stdout.write(`Joined network as '${name}'. Agent key saved.\n`);
+        return;
+    }
+    if (result.kind === "not_found") {
+        const mockKey = `phase0-mock-${(0, node_crypto_1.randomUUID)()}`;
+        await (0, config_1.patchConfig)({ agentKey: mockKey, agentName: name });
+        process.stdout.write("Warning: join API returned 404. Saved local mock agent key (Phase 1 network join).\n");
+        return;
+    }
+    printError(result.message);
+}
+function setupHeartbeat(message) {
+    process.stdout.write(`${message}\n`);
+    return setInterval(() => {
+        process.stdout.write(`[heartbeat] ${new Date().toISOString()}\n`);
+    }, 30_000);
+}
+async function tryConnectAgentWs(url) {
+    const wsCtor = globalThis.WebSocket;
+    if (!wsCtor) {
+        return false;
+    }
+    return await new Promise((resolve) => {
+        let settled = false;
+        const ws = new wsCtor(url);
+        const timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                ws.close();
+                resolve(false);
+            }
+        }, 4000);
+        ws.onopen = () => {
+            clearTimeout(timeout);
+            if (settled) {
+                return;
+            }
+            settled = true;
+            process.stdout.write(`Connected to ${url}\n`);
+            ws.onmessage = (event) => {
+                process.stdout.write(`[message] ${String(event.data)}\n`);
+            };
+            resolve(true);
+        };
+        ws.onerror = () => {
+            clearTimeout(timeout);
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(false);
+        };
+        ws.onclose = () => {
+            clearTimeout(timeout);
+            if (!settled) {
+                settled = true;
+                resolve(false);
+            }
+        };
+    });
+}
+async function cmdAgentRun() {
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const wsUrl = (0, network_1.toWsUrl)(networkUrl);
+    const connected = await tryConnectAgentWs(wsUrl);
+    const timer = setupHeartbeat(connected
+        ? "Agent loop active. Waiting for work..."
+        : "waiting for network WSS (Phase 1)");
+    const cleanup = () => {
+        clearInterval(timer);
+        process.stdout.write("Exiting agent loop.\n");
+        process.exit(0);
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+}
+async function cmdDiscover(args) {
+    const json = hasFlag(args, "--json");
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const discovered = await (0, network_1.discoverPeers)(networkUrl);
+    if (json) {
+        printJson({ peers: discovered.peers });
+        return;
+    }
+    if (discovered.peers.length === 0) {
+        process.stdout.write("No peers discovered.\n");
+        return;
+    }
+    process.stdout.write(`Discovered ${discovered.peers.length} peer(s):\n`);
+    for (const peer of discovered.peers) {
+        process.stdout.write(`- ${JSON.stringify(peer)}\n`);
+    }
+}
+async function cmdSend(args) {
+    const json = hasFlag(args, "--json");
+    const to = valueForFlag(args, "--to");
+    const text = valueForFlag(args, "--text");
+    if (!to || !text) {
+        printError("Usage: marshell send --to <name> --text \"...\" [--json]");
+    }
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.sendMessage)(networkUrl, to, text);
+    if (json) {
+        printJson(result);
+        return;
+    }
+    if (result.kind === "sent") {
+        process.stdout.write(`Sent message to '${to}' (id: ${result.id}).\n`);
+        return;
+    }
+    if (result.kind === "stubbed") {
+        process.stdout.write(`Warning: ${result.reason}\n`);
+        return;
+    }
+    printError(result.message);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printHelp();
+        return;
+    }
+    if (args[0] === "auth") {
+        const sub = args[1];
+        const rest = args.slice(2);
+        if (sub === "set") {
+            await cmdAuthSet(rest);
+            return;
+        }
+        if (sub === "status") {
+            await cmdAuthStatus(rest);
+            return;
+        }
+        printError("Unknown auth command. Try: marshell auth set|status");
+    }
+    if (args[0] === "agent") {
+        const sub = args[1];
+        const rest = args.slice(2);
+        if (sub === "join") {
+            await cmdAgentJoin(rest);
+            return;
+        }
+        if (sub === "run") {
+            await cmdAgentRun();
+            return;
+        }
+        printError("Unknown agent command. Try: marshell agent join|run");
+    }
+    if (args[0] === "discover") {
+        await cmdDiscover(args.slice(1));
+        return;
+    }
+    if (args[0] === "send") {
+        await cmdSend(args.slice(1));
+        return;
+    }
+    printError(`Unknown command '${args[0]}'. Run marshell --help`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    printError(message);
+});

package/dist/config.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNetworkUrl = getNetworkUrl;
+exports.getConfigPath = getConfigPath;
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.patchConfig = patchConfig;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const DEFAULT_NETWORK_URL = "https://network.marshell.dev";
+function getNetworkUrl(config) {
+    return (process.env.MARSHELL_NETWORK_URL ??
+        config?.networkUrl ??
+        DEFAULT_NETWORK_URL);
+}
+function getConfigPath() {
+    if (process.env.MARSHELL_CONFIG) {
+        return process.env.MARSHELL_CONFIG;
+    }
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".marshell", "config.json");
+}
+async function readConfig() {
+    const path = getConfigPath();
+    try {
+        const raw = await (0, promises_1.readFile)(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch (error) {
+        const maybeCode = error.code;
+        if (maybeCode === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+async function writeConfig(next) {
+    const path = getConfigPath();
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(path), { recursive: true });
+    await (0, promises_1.writeFile)(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+async function patchConfig(patch) {
+    const current = await readConfig();
+    const merged = {
+        ...current,
+        ...patch,
+        networkUrl: patch.networkUrl ?? getNetworkUrl(current),
+        updatedAt: new Date().toISOString(),
+    };
+    await writeConfig(merged);
+    return merged;
+}

package/dist/network.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pingNetwork = pingNetwork;
+exports.joinAgent = joinAgent;
+exports.discoverPeers = discoverPeers;
+exports.sendMessage = sendMessage;
+exports.toWsUrl = toWsUrl;
+const config_1 = require("./config");
+function normalizeBaseUrl(raw) {
+    return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+function withPath(baseUrl, path) {
+    return `${normalizeBaseUrl(baseUrl)}${path}`;
+}
+async function pingNetwork(baseUrl) {
+    const candidates = ["/health", "/v1/health"];
+    for (const path of candidates) {
+        try {
+            const response = await fetch(withPath(baseUrl, path), {
+                method: "GET",
+            });
+            if (response.ok) {
+                return { ok: true, status: response.status };
+            }
+            if (response.status !== 404) {
+                return {
+                    ok: false,
+                    status: response.status,
+                    message: `Health endpoint returned HTTP ${response.status}.`,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: error.message,
+            };
+        }
+    }
+    return {
+        ok: false,
+        message: "Health endpoint not found.",
+    };
+}
+async function postJson(url, body) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    let data = {};
+    if (text.trim().length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { raw: text };
+        }
+    }
+    return {
+        status: response.status,
+        data: data,
+    };
+}
+async function joinAgent(baseUrl, name) {
+    const config = await (0, config_1.readConfig)();
+    if (!config.token) {
+        return {
+            kind: "error",
+            status: 401,
+            message: "Missing auth token. Run: marshell auth set <token>",
+        };
+    }
+    try {
+        const result = await postJson(withPath(baseUrl, "/v1/agents/join"), {
+            token: config.token,
+            name,
+        });
+        if (result.status === 404) {
+            return { kind: "not_found" };
+        }
+        if (result.status >= 200 && result.status < 300 && result.data.agent_key) {
+            return { kind: "joined", agentKey: result.data.agent_key };
+        }
+        return {
+            kind: "error",
+            status: result.status,
+            message: `Join failed with HTTP ${result.status}.`,
+        };
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            status: 0,
+            message: error.message,
+        };
+    }
+}
+async function discoverPeers(baseUrl) {
+    const candidates = ["/v1/peers", "/v1/discover"];
+    for (const path of candidates) {
+        try {
+            const response = await fetch(withPath(baseUrl, path), {
+                method: "GET",
+            });
+            if (response.status === 404) {
+                continue;
+            }
+            if (response.ok) {
+                const data = (await response.json());
+                if (Array.isArray(data)) {
+                    return { peers: data };
+                }
+                return { peers: data.peers ?? [] };
+            }
+        }
+        catch {
+            return { peers: [] };
+        }
+    }
+    return { peers: [] };
+}
+async function sendMessage(baseUrl, to, text) {
+    const config = await (0, config_1.readConfig)();
+    if (!config.token) {
+        return { kind: "error", message: "Missing auth token." };
+    }
+    try {
+        const result = await postJson(withPath(baseUrl, "/v1/messages/send"), {
+            token: config.token,
+            to,
+            text,
+        });
+        if (result.status === 404) {
+            return {
+                kind: "stubbed",
+                reason: "Network send API is not available yet (Phase 1).",
+            };
+        }
+        if (result.status >= 200 && result.status < 300) {
+            return {
+                kind: "sent",
+                id: result.data.id ?? `local-${Date.now()}`,
+            };
+        }
+        return {
+            kind: "error",
+            status: result.status,
+            message: `Send failed with HTTP ${result.status}.`,
+        };
+    }
+    catch (error) {
+        return {
+            kind: "stubbed",
+            reason: `Network unavailable, stored as local stub: ${error.message}`,
+        };
+    }
+}
+function toWsUrl(httpBase) {
+    const url = new URL(httpBase);
+    if (url.protocol === "https:") {
+        url.protocol = "wss:";
+    }
+    else {
+        url.protocol = "ws:";
+    }
+    return `${url.toString().replace(/\/$/, "")}/v1/agents/ws`;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@marshell/cli",
+  "version": "0.1.0",
+  "description": "Marshell CLI — join a subnet, discover agents, send messages",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "marshell": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mfinikov/marshell"
+  },
+  "homepage": "https://marshell.dev",
+  "keywords": [
+    "marshell",
+    "agents",
+    "a2a",
+    "cli"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.16.11",
+    "typescript": "^5.6.3"
+  }
+}
+