@temet/cli 0.2.0

package/README.md

@@ -0,0 +1,57 @@
+# @temet/cli
+
+Temet CLI for MCP config setup.
+
+## Install / Run
+
+```bash
+pnpm dlx @temet/cli install-handler
+pnpm dlx @temet/cli connect --address <16hex> --token <token>
+```
+
+## Command
+
+```bash
+temet connect --address <16hex> --token <token> [--config-path <path>] [--relay-url <url>] [--name temet] [--dry-run]
+temet connect-url --url "temet://connect?address=<16hex>&token=<token>&relay=<url>&name=temet" [--config-path <path>] [--name temet] [--relay-url <url>] [--dry-run]
+temet install-handler [--dry-run]
+temet uninstall-handler [--dry-run]
+```
+
+## What it does
+
+- Creates or updates an MCP config file (default: `.mcp.json`)
+- Upserts a `temet` MCP HTTP server entry
+- Preserves existing MCP server entries
+- Accepts `temet://connect?...` deep links via `connect-url`
+- Installs native `temet://` protocol handler (macOS, Linux, Windows)
+
+## Native handler quickstart
+
+```bash
+pnpm dlx @temet/cli install-handler
+```
+
+Then use a Quick connect button in Temet UI.
+
+To remove:
+
+```bash
+pnpm dlx @temet/cli uninstall-handler
+```
+
+## Defaults
+
+- relay URL: `https://temet-relay.ramponneau.workers.dev/mcp`
+- config path: `./.mcp.json`
+- server name: `temet`
+
+## Notes
+
+V1 does not handle login or token generation. Get `address` and `token` from Temet Agent Hub.
+
+## Release automation
+
+- Versioning and changelog are managed by `release-please` for `packages/cli`.
+- npm publication is automated from GitHub Actions when a CLI release is created.
+- Required repo secret: `NPM_TOKEN` (npm token with publish rights for `@temet/cli`).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_RELAY_URL = "https://temet-relay.ramponneau.workers.dev/mcp";
+const DEFAULT_SERVER_NAME = "temet";
+const DEFAULT_PROTOCOL_APP_NAME = "Temet Handler";
+const LINUX_DESKTOP_ENTRY = "temet-handler.desktop";
+const LINUX_HANDLER_SCRIPT = "temet-protocol-handler";
+const HELP = `Temet CLI
+
+Usage:
+\ttemet connect --address <16hex> --token <token> [--config-path <path>] [--relay-url <url>] [--name temet] [--dry-run]
+\ttemet connect-url --url "temet://connect?address=<16hex>&token=<token>&relay=<url>&name=temet" [--config-path <path>] [--name temet] [--relay-url <url>] [--dry-run]
+\ttemet install-handler [--dry-run]
+\ttemet uninstall-handler [--dry-run]
+
+Examples:
+\ttemet connect --address a3f8c2d19f0b7e41 --token <token>
+\ttemet connect-url --url "temet://connect?address=a3f8c2d19f0b7e41&token=<token>&relay=https%3A%2F%2Ftemet-relay.ramponneau.workers.dev%2Fmcp"
+\tpnpm dlx @temet/cli install-handler
+\tpnpm dlx @temet/cli connect-url --url "temet://connect?address=a3f8c2d19f0b7e41&token=<token>"
+`;
+function printHelp(exitCode = 0) {
+    console.log(HELP);
+    process.exit(exitCode);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAddress(raw) {
+    const address = raw.trim().toLowerCase();
+    if (!/^[a-f0-9]{16}$/i.test(address)) {
+        throw new Error("Invalid address. Expected 16 hex chars.");
+    }
+    return address;
+}
+function parseFlagBag(args) {
+    const flags = new Map();
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === "--dry-run") {
+            flags.set("dry-run", true);
+            continue;
+        }
+        const key = arg.slice(2);
+        const value = args[i + 1];
+        if (!value || value.startsWith("--")) {
+            throw new Error(`Missing value for --${key}`);
+        }
+        flags.set(key, value);
+        i += 1;
+    }
+    return { flags, positionals };
+}
+function readOptionalString(flags, key) {
+    const value = flags.get(key);
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function parseConnectOptions(flags) {
+    const address = normalizeAddress(String(flags.get("address") ?? ""));
+    const token = String(flags.get("token") ?? "").trim();
+    const configPath = resolve(String(flags.get("config-path") ?? ".mcp.json").trim());
+    const relayUrl = String(flags.get("relay-url") ?? DEFAULT_RELAY_URL).trim();
+    const serverName = String(flags.get("name") ?? DEFAULT_SERVER_NAME).trim();
+    const dryRun = Boolean(flags.get("dry-run"));
+    if (token.length === 0) {
+        throw new Error("Missing --token.");
+    }
+    if (serverName.length === 0) {
+        throw new Error("Invalid --name.");
+    }
+    if (relayUrl.length === 0) {
+        throw new Error("Invalid --relay-url.");
+    }
+    return {
+        address,
+        token,
+        configPath,
+        relayUrl,
+        serverName,
+        dryRun,
+    };
+}
+function parseTemetDeepLink(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error("Invalid --url. Expected a valid temet:// URL.");
+    }
+    if (url.protocol !== "temet:") {
+        throw new Error("Invalid deep link protocol. Expected temet://");
+    }
+    const route = `${url.hostname}${url.pathname}`
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "")
+        .toLowerCase();
+    if (route !== "connect") {
+        throw new Error("Invalid deep link route. Expected temet://connect");
+    }
+    const address = normalizeAddress(url.searchParams.get("address") ?? "");
+    const token = (url.searchParams.get("token") ?? "").trim();
+    const relayUrl = (url.searchParams.get("relay") ?? DEFAULT_RELAY_URL).trim();
+    const serverName = (url.searchParams.get("name") ?? DEFAULT_SERVER_NAME).trim();
+    if (token.length === 0) {
+        throw new Error("Deep link missing token parameter.");
+    }
+    if (relayUrl.length === 0) {
+        throw new Error("Deep link has empty relay parameter.");
+    }
+    if (serverName.length === 0) {
+        throw new Error("Deep link has empty name parameter.");
+    }
+    return { address, token, relayUrl, serverName };
+}
+function parseConnectUrlOptions(flags, positionals) {
+    const deeplink = readOptionalString(flags, "url") ?? positionals[0] ?? "";
+    if (!deeplink) {
+        throw new Error("Missing --url for connect-url command.");
+    }
+    const parsed = parseTemetDeepLink(deeplink);
+    const configPath = resolve(String(flags.get("config-path") ?? ".mcp.json").trim());
+    const relayUrl = readOptionalString(flags, "relay-url") ??
+        parsed.relayUrl ??
+        DEFAULT_RELAY_URL;
+    const serverName = readOptionalString(flags, "name") ??
+        parsed.serverName ??
+        DEFAULT_SERVER_NAME;
+    const dryRun = Boolean(flags.get("dry-run"));
+    return {
+        address: parsed.address,
+        token: parsed.token,
+        configPath,
+        relayUrl,
+        serverName,
+        dryRun,
+    };
+}
+function parseArgs(argv) {
+    if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+        printHelp(0);
+    }
+    const [command, ...rest] = argv;
+    const { flags, positionals } = parseFlagBag(rest);
+    const dryRun = Boolean(flags.get("dry-run"));
+    if (command === "connect") {
+        return {
+            command,
+            options: parseConnectOptions(flags),
+        };
+    }
+    if (command === "connect-url") {
+        return {
+            command,
+            options: parseConnectUrlOptions(flags, positionals),
+        };
+    }
+    if (command === "install-handler" || command === "uninstall-handler") {
+        return { command, dryRun };
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp(1);
+}
+async function readConfig(configPath) {
+    try {
+        const content = await readFile(configPath, "utf8");
+        if (!content.trim())
+            return {};
+        const parsed = JSON.parse(content);
+        if (!isObject(parsed)) {
+            throw new Error("MCP config must be a JSON object.");
+        }
+        return parsed;
+    }
+    catch (error) {
+        const e = error;
+        if (e.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+function buildServerEntry(opts) {
+    return {
+        type: "http",
+        url: opts.relayUrl,
+        headers: {
+            "X-Temet-Address": opts.address,
+            Authorization: `Bearer ${opts.token}`,
+        },
+    };
+}
+function upsertServer(config, serverName, entry) {
+    if (isObject(config.mcpServers)) {
+        const servers = config.mcpServers;
+        servers[serverName] = entry;
+        config.mcpServers = servers;
+        return config;
+    }
+    // Fresh or flat config — always wrap in mcpServers (Claude Code / Cursor expect this)
+    config.mcpServers = { [serverName]: entry };
+    return config;
+}
+async function writeConfig(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+}
+async function runWriteFlow(command, opts) {
+    const current = await readConfig(opts.configPath);
+    const next = upsertServer(current, opts.serverName, buildServerEntry(opts));
+    if (opts.dryRun) {
+        console.log("[temet] dry-run: config preview");
+        console.log(JSON.stringify(next, null, "\t"));
+        return;
+    }
+    await writeConfig(opts.configPath, next);
+    console.log(`[temet] config updated: ${opts.configPath}`);
+    console.log(`[temet] server: ${opts.serverName}`);
+    console.log(`[temet] source: ${command}`);
+    console.log("[temet] next: restart your MCP client (Claude Code/Cursor/Codex).");
+}
+async function resolveBinary(name) {
+    try {
+        if (process.platform === "win32") {
+            const { stdout } = await execFileAsync("where", [name]);
+            const line = stdout
+                .split(/\r?\n/)
+                .map((entry) => entry.trim())
+                .find((entry) => entry.length > 0);
+            return line ?? null;
+        }
+        const { stdout } = await execFileAsync("which", [name]);
+        const line = stdout
+            .split(/\r?\n/)
+            .map((entry) => entry.trim())
+            .find((entry) => entry.length > 0);
+        return line ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+function buildProtocolHandlerScript(temetBin, pnpmBin) {
+    const temetRunner = temetBin
+        ? `${shQuote(temetBin)} connect-url --url "$URL"`
+        : null;
+    const pnpmRunner = pnpmBin
+        ? `${shQuote(pnpmBin)} dlx @temet/cli connect-url --url "$URL"`
+        : null;
+    const runLine = temetRunner ??
+        pnpmRunner ??
+        `echo "[temet] no runner found (need temet or pnpm in PATH)"`;
+    return `#!/bin/sh
+URL="$1"
+LOG_DIR="$HOME/.temet"
+LOG_FILE="$LOG_DIR/handler.log"
+
+mkdir -p "$LOG_DIR"
+
+{
+	echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] handler URL: $URL"
+	if [ -z "$URL" ]; then
+		echo "[temet] empty URL"
+		exit 1
+	fi
+	${runLine}
+	STATUS=$?
+	if [ "$STATUS" -ne 0 ]; then
+		echo "[temet] handler failed with exit $STATUS"
+		exit "$STATUS"
+	fi
+	echo "[temet] handler success"
+} >> "$LOG_FILE" 2>&1
+`;
+}
+async function safeExec(command, args, errorHint) {
+    try {
+        await execFileAsync(command, args);
+    }
+    catch {
+        console.warn(`[temet] warning: ${errorHint}`);
+    }
+}
+async function installMacHandler(dryRun) {
+    const appDir = resolve(homedir(), "Applications", `${DEFAULT_PROTOCOL_APP_NAME}.app`);
+    const contentsDir = resolve(appDir, "Contents");
+    const macOSDir = resolve(contentsDir, "MacOS");
+    const executablePath = resolve(macOSDir, "temet-handler");
+    const infoPlistPath = resolve(contentsDir, "Info.plist");
+    const lsregisterPath = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+    const temetBin = await resolveBinary("temet");
+    const pnpmBin = await resolveBinary("pnpm");
+    const script = buildProtocolHandlerScript(temetBin, pnpmBin);
+    const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key>
+	<string>${DEFAULT_PROTOCOL_APP_NAME}</string>
+	<key>CFBundleDisplayName</key>
+	<string>${DEFAULT_PROTOCOL_APP_NAME}</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.temet.protocol-handler</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleExecutable</key>
+	<string>temet-handler</string>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>Temet Protocol</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>temet</string>
+			</array>
+		</dict>
+	</array>
+</dict>
+</plist>
+`;
+    if (dryRun) {
+        console.log(`[temet] dry-run macOS install path: ${appDir}`);
+        console.log(`[temet] dry-run executable: ${executablePath}`);
+        return;
+    }
+    await mkdir(macOSDir, { recursive: true });
+    await writeFile(infoPlistPath, infoPlist, "utf8");
+    await writeFile(executablePath, script, "utf8");
+    await chmod(executablePath, 0o755);
+    await safeExec(lsregisterPath, ["-f", appDir], "unable to refresh LaunchServices registration (you may need to open the app once)");
+    console.log(`[temet] macOS handler installed: ${appDir}`);
+    if (!temetBin && !pnpmBin) {
+        console.log("[temet] warning: neither 'temet' nor 'pnpm' was found in PATH during install.");
+    }
+}
+async function uninstallMacHandler(dryRun) {
+    const appDir = resolve(homedir(), "Applications", `${DEFAULT_PROTOCOL_APP_NAME}.app`);
+    const lsregisterPath = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+    if (dryRun) {
+        console.log(`[temet] dry-run macOS uninstall path: ${appDir}`);
+        return;
+    }
+    await safeExec(lsregisterPath, ["-u", appDir], "unable to unregister LaunchServices entry");
+    await rm(appDir, { recursive: true, force: true });
+    console.log(`[temet] macOS handler removed: ${appDir}`);
+}
+async function installLinuxHandler(dryRun) {
+    const localShare = resolve(homedir(), ".local", "share", "applications");
+    const localBin = resolve(homedir(), ".local", "bin");
+    const desktopPath = resolve(localShare, LINUX_DESKTOP_ENTRY);
+    const scriptPath = resolve(localBin, LINUX_HANDLER_SCRIPT);
+    const temetBin = await resolveBinary("temet");
+    const pnpmBin = await resolveBinary("pnpm");
+    const script = buildProtocolHandlerScript(temetBin, pnpmBin);
+    const desktopEntry = `[Desktop Entry]
+Name=Temet Protocol Handler
+Exec=${scriptPath} %u
+Type=Application
+Terminal=false
+NoDisplay=true
+MimeType=x-scheme-handler/temet;
+`;
+    if (dryRun) {
+        console.log(`[temet] dry-run linux desktop file: ${desktopPath}`);
+        console.log(`[temet] dry-run linux script path: ${scriptPath}`);
+        return;
+    }
+    await mkdir(localShare, { recursive: true });
+    await mkdir(localBin, { recursive: true });
+    await writeFile(scriptPath, script, "utf8");
+    await chmod(scriptPath, 0o755);
+    await writeFile(desktopPath, desktopEntry, "utf8");
+    await safeExec("xdg-mime", ["default", LINUX_DESKTOP_ENTRY, "x-scheme-handler/temet"], "xdg-mime registration failed. Try running it manually.");
+    await safeExec("update-desktop-database", [localShare], "update-desktop-database not available");
+    console.log(`[temet] linux handler installed: ${desktopPath}`);
+}
+async function uninstallLinuxHandler(dryRun) {
+    const localShare = resolve(homedir(), ".local", "share", "applications");
+    const localBin = resolve(homedir(), ".local", "bin");
+    const desktopPath = resolve(localShare, LINUX_DESKTOP_ENTRY);
+    const scriptPath = resolve(localBin, LINUX_HANDLER_SCRIPT);
+    if (dryRun) {
+        console.log(`[temet] dry-run linux uninstall desktop file: ${desktopPath}`);
+        console.log(`[temet] dry-run linux uninstall script path: ${scriptPath}`);
+        return;
+    }
+    await rm(desktopPath, { force: true });
+    await rm(scriptPath, { force: true });
+    console.log(`[temet] linux handler removed`);
+}
+async function installWindowsHandler(dryRun) {
+    const temetBin = await resolveBinary("temet");
+    const pnpmBin = await resolveBinary("pnpm");
+    const runner = temetBin
+        ? `"${temetBin}" connect-url --url "%1"`
+        : pnpmBin
+            ? `"${pnpmBin}" dlx @temet/cli connect-url --url "%1"`
+            : `temet connect-url --url "%1"`;
+    const commandValue = `cmd.exe /d /s /c ${runner}`;
+    if (dryRun) {
+        console.log(`[temet] dry-run windows command: ${commandValue}`);
+        return;
+    }
+    await execFileAsync("reg", [
+        "add",
+        "HKCU\\Software\\Classes\\temet",
+        "/ve",
+        "/d",
+        "URL:Temet Protocol",
+        "/f",
+    ]);
+    await execFileAsync("reg", [
+        "add",
+        "HKCU\\Software\\Classes\\temet",
+        "/v",
+        "URL Protocol",
+        "/d",
+        "",
+        "/f",
+    ]);
+    await execFileAsync("reg", [
+        "add",
+        "HKCU\\Software\\Classes\\temet\\shell\\open\\command",
+        "/ve",
+        "/d",
+        commandValue,
+        "/f",
+    ]);
+    console.log("[temet] windows handler installed (HKCU\\Software\\Classes\\temet)");
+}
+async function uninstallWindowsHandler(dryRun) {
+    if (dryRun) {
+        console.log("[temet] dry-run windows uninstall key: HKCU\\Software\\Classes\\temet");
+        return;
+    }
+    await execFileAsync("reg", [
+        "delete",
+        "HKCU\\Software\\Classes\\temet",
+        "/f",
+    ]);
+    console.log("[temet] windows handler removed (HKCU\\Software\\Classes\\temet)");
+}
+async function installProtocolHandler(dryRun) {
+    if (process.platform === "darwin") {
+        await installMacHandler(dryRun);
+        return;
+    }
+    if (process.platform === "linux") {
+        await installLinuxHandler(dryRun);
+        return;
+    }
+    if (process.platform === "win32") {
+        await installWindowsHandler(dryRun);
+        return;
+    }
+    throw new Error(`Unsupported platform: ${process.platform}`);
+}
+async function uninstallProtocolHandler(dryRun) {
+    if (process.platform === "darwin") {
+        await uninstallMacHandler(dryRun);
+        return;
+    }
+    if (process.platform === "linux") {
+        await uninstallLinuxHandler(dryRun);
+        return;
+    }
+    if (process.platform === "win32") {
+        await uninstallWindowsHandler(dryRun);
+        return;
+    }
+    throw new Error(`Unsupported platform: ${process.platform}`);
+}
+async function run() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.command === "connect" || parsed.command === "connect-url") {
+        await runWriteFlow(parsed.command, parsed.options);
+        return;
+    }
+    if (parsed.command === "install-handler") {
+        await installProtocolHandler(parsed.dryRun);
+        console.log("[temet] next: click a Quick connect button in Temet.");
+        return;
+    }
+    if (parsed.command === "uninstall-handler") {
+        await uninstallProtocolHandler(parsed.dryRun);
+        return;
+    }
+    throw new Error(`Unhandled command: ${parsed.command}`);
+}
+run().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[temet] error: ${message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@temet/cli",
+	"version": "0.2.0",
+	"description": "Temet CLI for MCP configuration",
+	"keywords": [
+		"temet",
+		"mcp",
+		"byoa",
+		"cli",
+		"agent"
+	],
+	"license": "MIT",
+	"homepage": "https://temetapp.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ramponneau/temet.git",
+		"directory": "packages/cli"
+	},
+	"bugs": {
+		"url": "https://github.com/ramponneau/temet/issues"
+	},
+	"type": "module",
+	"bin": {
+		"temet": "dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"typecheck": "tsc --noEmit -p tsconfig.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}