kleos-cli 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -0
- package/dist/cli.js +34 -0
- package/dist/cliente.js +134 -0
- package/dist/comandos.js +448 -0
- package/dist/config.js +76 -0
- package/dist/erros.js +40 -0
- package/dist/navegador.js +69 -0
- package/dist/oauth.js +150 -0
- package/dist/ponte.js +51 -0
- package/dist/principal.js +174 -0
- package/dist/saida.js +75 -0
- package/dist/sessao.js +22 -0
- package/dist/skill.js +40 -0
- package/package.json +40 -0
- package/skills/kleos/SKILL.md +122 -0
- package/skills/kleos-cli/SKILL.md +100 -0
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# kleos
|
|
2
|
+
|
|
3
|
+
A CLI do [Kleos](https://ugc.zurc.app): gere, revise, agende e meça posts UGC
|
|
4
|
+
do seu app no TikTok e no Instagram pelo terminal — ou pelo agente de IA que
|
|
5
|
+
roda comandos (OpenClaw, Codex, Hermes, CI, cron).
|
|
6
|
+
|
|
7
|
+
É um cliente do mesmo servidor MCP que o Claude e o Cursor usam
|
|
8
|
+
(`https://mcp.zurc.app/mcp`): cada comando é uma chamada de ferramenta, com o
|
|
9
|
+
mesmo plano, as mesmas cotas e as mesmas regras. Node 22 ou mais novo; nenhuma
|
|
10
|
+
dependência em tempo de execução.
|
|
11
|
+
|
|
12
|
+
## Começar
|
|
13
|
+
|
|
14
|
+
1. Entre pelo navegador — sem chave para criar nem copiar:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx -y kleos-cli login
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
O navegador abre na tela do Kleos: entre com a sua conta, escolha a
|
|
21
|
+
organização, o projeto e o que a CLI pode fazer (ler, gerar, publicar) e
|
|
22
|
+
aprove. É OAuth 2.1 com PKCE: a CLI registra-se no servidor de login para a
|
|
23
|
+
porta local (`127.0.0.1:47651`, ou outra livre), recebe o código ali, troca
|
|
24
|
+
pelo token e grava em `~/.config/kleos/config.json` (permissão 600). O token
|
|
25
|
+
renova sozinho. `--no-browser` só imprime o endereço (SSH). Desconectar de
|
|
26
|
+
vez: Configurações › Chaves de API › Apps conectados.
|
|
27
|
+
|
|
28
|
+
2. Sem gente por perto (servidor, CI, cron), use uma **chave de API**: quem é
|
|
29
|
+
dono da organização cria em Configurações › Chaves de API
|
|
30
|
+
(https://ugc.zurc.app/settings/chaves).
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx -y kleos-cli login --key kleos_sk_…
|
|
34
|
+
# ou, em servidor/CI:
|
|
35
|
+
export KLEOS_API_KEY="kleos_sk_…"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`KLEOS_API_KEY` e `KLEOS_MCP_URL` no ambiente sobrepõem o arquivo.
|
|
39
|
+
|
|
40
|
+
3. Use:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
kleos whoami
|
|
44
|
+
kleos projects list
|
|
45
|
+
kleos posts generate --project habi --agent bia --count 10 --dry-run
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Comandos
|
|
49
|
+
|
|
50
|
+
| Comando | O que faz | Ferramenta |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| `kleos login` / `login --key` / `logout` | entra pelo navegador (OAuth) ou guarda a chave / apaga | `whoami` |
|
|
53
|
+
| `kleos whoami` | conta, plano, camadas e escopos do login ou da chave | `whoami` |
|
|
54
|
+
| `kleos usage` | o que o plano permite e quanto sobra | `get_usage` |
|
|
55
|
+
| `kleos projects list` | projetos (apps) | `list_projects` |
|
|
56
|
+
| `kleos agents list --project <p>` | agentes, contas, aprovações pendentes | `list_agents` |
|
|
57
|
+
| `kleos posts generate` | gera N posts (`--count`, `--format`, `--playbook`, `--at`, `--dry-run`, `--yes`) | `generate_posts` |
|
|
58
|
+
| `kleos posts list` | por período, estado, agente | `list_posts` |
|
|
59
|
+
| `kleos posts show <id>` | slides, legenda, publicações | `get_post` |
|
|
60
|
+
| `kleos posts approve <id>…` | aprova (publica em conta real) | `approve_posts` |
|
|
61
|
+
| `kleos posts schedule <id> --account …` | agenda em conta(s) | `schedule_post` |
|
|
62
|
+
| `kleos week plan` | planeja os próximos dias | `plan_week` |
|
|
63
|
+
| `kleos jobs wait <job_id>` | espera um trabalho da fila | `get_job` |
|
|
64
|
+
| `kleos metrics [--since 7d]` | resultados do período | `get_metrics` |
|
|
65
|
+
| `kleos call <ferramenta> --args '<json>'` | qualquer ferramenta do MCP | — |
|
|
66
|
+
| `kleos mcp` | ponte stdio → HTTP para cliente que só fala stdio | — |
|
|
67
|
+
| `kleos skill install` | instala a skill no Claude Code, Codex, Hermes e OpenClaw | — |
|
|
68
|
+
|
|
69
|
+
`kleos <comando> --help` mostra as opções e exemplos. A lista das ferramentas
|
|
70
|
+
com parâmetros: https://ugc.zurc.app/llms-full.txt
|
|
71
|
+
|
|
72
|
+
## Para agentes e scripts
|
|
73
|
+
|
|
74
|
+
- `--json` em todo comando; é o padrão quando o stdout não é terminal. O
|
|
75
|
+
resultado sai no stdout; o erro, no stderr, como
|
|
76
|
+
`{"error": "…", "exit_code": 3, "details": {…}}`.
|
|
77
|
+
- Códigos de saída:
|
|
78
|
+
|
|
79
|
+
| Código | Quando |
|
|
80
|
+
|---|---|
|
|
81
|
+
| 0 | deu certo |
|
|
82
|
+
| 1 | erro (rede, chave inválida ou login vencido, servidor, trabalho que falhou) |
|
|
83
|
+
| 2 | uso errado (comando, flag, parâmetro) |
|
|
84
|
+
| 3 | limite ou cota do plano — não repita em laço |
|
|
85
|
+
| 4 | falta aprovação humana (gasto grande: rode de novo com `--yes`), escopo da chave ou camada do plano |
|
|
86
|
+
|
|
87
|
+
- Nada é interativo sem pedir: gasto grande (mais de 10 posts, ou mais do que
|
|
88
|
+
sobra no plano) sai com 4 e a estimativa; `--yes` confirma.
|
|
89
|
+
- Toda escrita manda uma `idempotency_key` nova; `--idempotency-key` fixa uma
|
|
90
|
+
para repetir com segurança.
|
|
91
|
+
|
|
92
|
+
## Clientes só-stdio
|
|
93
|
+
|
|
94
|
+
O Claude Desktop e o ChatGPT conectam direto pela URL
|
|
95
|
+
(`https://mcp.zurc.app/mcp`, com login). Para cliente que só fala stdio, a
|
|
96
|
+
ponte usa o login da CLI (`kleos login` antes) ou a chave:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"mcpServers": {
|
|
101
|
+
"kleos": { "command": "npx", "args": ["-y", "kleos-cli", "mcp"], "env": { "KLEOS_API_KEY": "kleos_sk_…" } }
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Desenvolvimento
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npm test # vitest, com fetch falso — não chama o servidor
|
|
110
|
+
npm run build # tsc → dist/, e copia ../skills para skills/
|
|
111
|
+
npm pack --dry-run # confere o que entra no pacote
|
|
112
|
+
KLEOS_MCP_URL=http://127.0.0.1:3000/mcp node dist/cli.js whoami
|
|
113
|
+
```
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { createInterface } from "node:readline/promises";
|
|
5
|
+
import { setTimeout as esperar } from "node:timers/promises";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
import { abrirNavegador, ouvirCallback } from "./navegador.js";
|
|
8
|
+
import { principal } from "./principal.js";
|
|
9
|
+
/** O binário `kleos`: liga a CLI ao processo. A lógica mora em `principal.ts`. */
|
|
10
|
+
const pacote = dirname(dirname(fileURLToPath(import.meta.url)));
|
|
11
|
+
const codigo = await principal(process.argv.slice(2), {
|
|
12
|
+
fetch: globalThis.fetch,
|
|
13
|
+
env: process.env,
|
|
14
|
+
home: homedir(),
|
|
15
|
+
stdin: process.stdin,
|
|
16
|
+
stdout: process.stdout,
|
|
17
|
+
stderr: process.stderr,
|
|
18
|
+
stdinTTY: Boolean(process.stdin.isTTY),
|
|
19
|
+
agora: () => new Date(),
|
|
20
|
+
esperar: (ms) => esperar(ms).then(() => undefined),
|
|
21
|
+
origemDasSkills: join(pacote, "skills"),
|
|
22
|
+
abrirNavegador,
|
|
23
|
+
ouvirCallback,
|
|
24
|
+
async perguntar(pergunta) {
|
|
25
|
+
const rl = createInterface({ input: process.stdin, output: process.stderr });
|
|
26
|
+
try {
|
|
27
|
+
return await rl.question(pergunta);
|
|
28
|
+
}
|
|
29
|
+
finally {
|
|
30
|
+
rl.close();
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
}, Boolean(process.stdout.isTTY));
|
|
34
|
+
process.exitCode = codigo;
|
package/dist/cliente.js
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { ErroDaCli, SAIDA, saidaDoCodigo } from "./erros.js";
|
|
2
|
+
/**
|
|
3
|
+
* O cliente do `/mcp` do Kleos. A CLI **não** fala com rotas internas: todo
|
|
4
|
+
* comando vira um `tools/call`, e a paridade entre CLI e MCP não depende de
|
|
5
|
+
* disciplina (`docs/AGENTES_MCP_CLI.md`, seção 3). O servidor é sem estado
|
|
6
|
+
* (Streamable HTTP, spec 2026-07-28): sem `initialize`, sem sessão.
|
|
7
|
+
*/
|
|
8
|
+
export const VERSAO = "0.1.0";
|
|
9
|
+
export const ACEITA = "application/json, text/event-stream";
|
|
10
|
+
/**
|
|
11
|
+
* O corpo de uma resposta do `/mcp`: JSON puro ou SSE (o modo sem estado de
|
|
12
|
+
* 2025 responde em `event: message` / `data: …`). Devolve todas as mensagens.
|
|
13
|
+
*/
|
|
14
|
+
export function lerMensagens(texto, tipo) {
|
|
15
|
+
const corpo = texto.trim();
|
|
16
|
+
if (!corpo)
|
|
17
|
+
return [];
|
|
18
|
+
const sse = (tipo ?? "").includes("text/event-stream") || /^(event|data|id|retry):/m.test(corpo.split("\n")[0] ?? "");
|
|
19
|
+
if (!sse) {
|
|
20
|
+
const json = JSON.parse(corpo);
|
|
21
|
+
return Array.isArray(json) ? json : [json];
|
|
22
|
+
}
|
|
23
|
+
const mensagens = [];
|
|
24
|
+
// Cada evento termina numa linha vazia; `data:` de várias linhas se juntam com \n.
|
|
25
|
+
for (const evento of corpo.split(/\r?\n\r?\n/)) {
|
|
26
|
+
const dados = evento
|
|
27
|
+
.split(/\r?\n/)
|
|
28
|
+
.filter((l) => l.startsWith("data:"))
|
|
29
|
+
.map((l) => l.slice(5).replace(/^ /, ""))
|
|
30
|
+
.join("\n");
|
|
31
|
+
if (!dados)
|
|
32
|
+
continue;
|
|
33
|
+
const json = JSON.parse(dados);
|
|
34
|
+
mensagens.push(...(Array.isArray(json) ? json : [json]));
|
|
35
|
+
}
|
|
36
|
+
return mensagens;
|
|
37
|
+
}
|
|
38
|
+
const semChave = () => new ErroDaCli("Sem chave de API nem login. Rode `kleos login` (entra pelo navegador), ou `kleos login --key kleos_sk_…` / KLEOS_API_KEY para rodar sem gente. A chave é criada em Configurações › Chaves de API (https://ugc.zurc.app/settings/chaves).", SAIDA.erro);
|
|
39
|
+
/** A mensagem de erro que o servidor mandou num corpo JSON-RPC ou `{ error }`. */
|
|
40
|
+
function mensagemDoCorpo(texto) {
|
|
41
|
+
try {
|
|
42
|
+
const c = JSON.parse(texto);
|
|
43
|
+
if (typeof c.error === "string")
|
|
44
|
+
return c.error;
|
|
45
|
+
if (c.error && typeof c.error === "object" && typeof c.error.message === "string")
|
|
46
|
+
return c.error.message;
|
|
47
|
+
}
|
|
48
|
+
catch {
|
|
49
|
+
// corpo não é JSON
|
|
50
|
+
}
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
/** Um POST ao `/mcp` com a chave. Erros de HTTP viram `ErroDaCli` com o código de saída certo. */
|
|
54
|
+
export async function postar(con, corpo, extras = {}) {
|
|
55
|
+
if (!con.apiKey)
|
|
56
|
+
throw semChave();
|
|
57
|
+
const enviar = async (token) => {
|
|
58
|
+
try {
|
|
59
|
+
return await con.fetch(con.mcpUrl, {
|
|
60
|
+
method: "POST",
|
|
61
|
+
headers: { "content-type": "application/json", accept: ACEITA, authorization: `Bearer ${token}`, "user-agent": `kleos-cli/${VERSAO}`, ...extras },
|
|
62
|
+
body: JSON.stringify(corpo),
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
catch (e) {
|
|
66
|
+
throw new ErroDaCli(`Não deu para falar com ${con.mcpUrl}: ${e.message}`, SAIDA.erro);
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
let resposta = await enviar(con.apiKey);
|
|
70
|
+
if (resposta.status === 401 && con.renovar) {
|
|
71
|
+
const novo = await con.renovar().catch(() => null);
|
|
72
|
+
if (novo) {
|
|
73
|
+
con.apiKey = novo;
|
|
74
|
+
resposta = await enviar(novo);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
const texto = await resposta.text();
|
|
78
|
+
if (resposta.status === 401) {
|
|
79
|
+
const padrao = con.renovar ? "O login expirou ou foi desconectado. Rode kleos login de novo." : "Chave de API inválida.";
|
|
80
|
+
throw new ErroDaCli(`${mensagemDoCorpo(texto) ?? padrao} (HTTP 401)`, SAIDA.erro, { code: "nao_autorizado", status: 401 });
|
|
81
|
+
}
|
|
82
|
+
if (resposta.status === 429) {
|
|
83
|
+
const espera = resposta.headers.get("retry-after");
|
|
84
|
+
throw new ErroDaCli(mensagemDoCorpo(texto) ?? `Muitas chamadas por minuto com esta chave${espera ? `; espere ${espera}s` : ""}.`, SAIDA.limite, { code: "limite", status: 429, retry_after: espera });
|
|
85
|
+
}
|
|
86
|
+
if (resposta.status === 202 || resposta.status === 204)
|
|
87
|
+
return { status: resposta.status, mensagens: [], cabecalhos: resposta.headers };
|
|
88
|
+
if (!resposta.ok) {
|
|
89
|
+
throw new ErroDaCli(`${mensagemDoCorpo(texto) ?? "O Kleos recusou a chamada."} (HTTP ${resposta.status})`, SAIDA.erro, { status: resposta.status });
|
|
90
|
+
}
|
|
91
|
+
try {
|
|
92
|
+
return { status: resposta.status, mensagens: lerMensagens(texto, resposta.headers.get("content-type")), cabecalhos: resposta.headers };
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
throw new ErroDaCli(`Resposta que não deu para ler de ${con.mcpUrl} (HTTP ${resposta.status}).`, SAIDA.erro);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
let proximoId = 0;
|
|
99
|
+
/**
|
|
100
|
+
* `tools/call`: devolve o `structuredContent` da ferramenta. Erro de
|
|
101
|
+
* ferramenta (`isError`) vira `ErroDaCli` com o código de saída do `code`
|
|
102
|
+
* (limite → 3; escopo, camada → 4; parâmetro → 2).
|
|
103
|
+
*/
|
|
104
|
+
export async function chamarFerramenta(con, nome, args = {}) {
|
|
105
|
+
const id = ++proximoId;
|
|
106
|
+
const { mensagens } = await postar(con, { jsonrpc: "2.0", id, method: "tools/call", params: { name: nome, arguments: args } });
|
|
107
|
+
const msg = mensagens.find((m) => m.id === id) ?? mensagens.find((m) => m.result !== undefined || m.error !== undefined);
|
|
108
|
+
if (!msg)
|
|
109
|
+
throw new ErroDaCli(`O Kleos não respondeu a ${nome}.`, SAIDA.erro);
|
|
110
|
+
if (msg.error) {
|
|
111
|
+
// -32602: parâmetros inválidos; -32601: ferramenta que não existe.
|
|
112
|
+
const uso = msg.error.code === -32602 || msg.error.code === -32601;
|
|
113
|
+
throw new ErroDaCli(msg.error.message, uso ? SAIDA.uso : SAIDA.erro, { code: msg.error.code, data: msg.error.data });
|
|
114
|
+
}
|
|
115
|
+
const r = (msg.result ?? {});
|
|
116
|
+
const dados = r.structuredContent ?? lerTexto(r);
|
|
117
|
+
if (r.isError) {
|
|
118
|
+
const mensagem = typeof dados.error === "string" ? dados.error : (r.content?.[0]?.text ?? `${nome} falhou.`).split("\n")[0];
|
|
119
|
+
throw new ErroDaCli(mensagem, saidaDoCodigo(dados.code), dados);
|
|
120
|
+
}
|
|
121
|
+
return dados;
|
|
122
|
+
}
|
|
123
|
+
function lerTexto(r) {
|
|
124
|
+
const texto = r.content?.find((c) => c.type === "text")?.text;
|
|
125
|
+
if (!texto)
|
|
126
|
+
return {};
|
|
127
|
+
try {
|
|
128
|
+
const json = JSON.parse(texto);
|
|
129
|
+
return json && typeof json === "object" ? json : { value: json };
|
|
130
|
+
}
|
|
131
|
+
catch {
|
|
132
|
+
return { text: texto };
|
|
133
|
+
}
|
|
134
|
+
}
|