@aiuby-ia/cli 0.0.0-stage → 0.3.0

package/docs/api.md

@@ -0,0 +1,115 @@
+# Referência da API do Compute
+
+Base: `https://aiuby.com/api/platform/compute`. Respostas em JSON. 
+
+## Autenticação
+
+- **Leitura (`GET`)**: sessão da área logada, ou `Authorization: Bearer <chave>` com uma chave
+  de API de escopo `compute:read`. A chave vale para um workspace.
+- **Escrita (`POST`)**: sessão de uma pessoa com permissão de gerenciar o workspace, ou chave
+  de API com o escopo `compute:write`. Limite: 30 alterações por minuto por pessoa ou chave.
+  O escopo `compute:write` não inclui leitura: para ler, a chave precisa também de `compute:read`.
+
+## Erros
+
+```json
+{ "error": { "code": "compute_not_deployable", "message": "..." } }
+```
+
+`code` aparece só em alguns erros. Status usados: `400` dados inválidos, `401` sem
+autenticação, `403` sem permissão, `404` não encontrado ou Compute não contratado,
+`409` conflito, `429` muitas chamadas.
+
+## Leitura
+
+### `GET /whoami`
+
+```json
+{ "organization": "Acme", "workspace": "Principal", "workspaceSlug": "principal",
+  "organizationId": "...", "workspaceId": "...", "kind": "credential", "role": null }
+```
+
+### `GET /apps`
+
+```json
+{ "apps": [ { "id": "...", "slug": "minha-api", "name": "Minha API", "currentRevision": 1,
+  "archived": false, "createdAt": "2026-11-12T12:00:00.000Z", "runtime": "container",
+  "hardwareLabel": "1 vCPU · 512 MB", "region": null } ] }
+```
+
+### `GET /apps/{ref}`
+
+`ref` é o id ou o identificador (slug). Devolve os campos da listagem mais `revisions`:
+`[{ "revision": 1, "createdAt": "...", "config": { ... } }]`. Revisões são imutáveis.
+
+### `GET /apps/{ref}/plan`
+
+O plano de implantação da revisão atual. Só leitura.
+
+```json
+{ "deployable": false, "provider": null, "sku": null, "preview": false,
+  "blockers": ["runtime_not_enabled"],
+  "reasons": [ { "code": "runtime_not_enabled", "message": "A execução de aplicações ainda não está habilitada nesta plataforma." } ] }
+```
+
+Bloqueios possíveis: `runtime_not_enabled`, `provider_not_enabled`, `sku_unknown`,
+`gpu_count_unsupported`, `quota_unverified`, `no_rate_card`, `no_budget`, `build_not_supported`,
+`preview_limits`, `preview_capacity`.
+
+### `GET /capacity`
+
+`hardware`: o catálogo de referência, cada item com `availability: "unverified"`.
+`providers`: o que cada adaptador de nuvem implementa hoje.
+
+### `GET /templates`
+
+`templates`: os modelos de partida, com a configuração inicial de cada um.
+
+## Escrita
+
+### `POST /apps`
+
+Cadastra a aplicação com a primeira revisão. Nada é implantado. Responde `201`.
+
+```json
+{ "name": "Minha API", "slug": "minha-api",
+  "config": { "runtime": "container", "image": "REGISTRO/minha-api:1", "port": 8080,
+    "hardware": { "provider": "any", "cpu": 1, "memoryMb": 512 },
+    "scaling": { "minReplicas": 0, "maxReplicas": 2 } } }
+```
+
+Regras: `slug` com 3 a 40 caracteres (minúsculas, dígitos e hífen, começando por letra),
+único no workspace; `runtime` `container` exige `image`; campos desconhecidos são recusados.
+Limites: 50 aplicações por workspace, 200 revisões por aplicação.
+
+### `POST /apps/{id}/revisions`
+
+Corpo: a nova `config`. Cria uma revisão e a torna a atual. Responde `201`.
+
+### `POST /apps/{id}/archive`
+
+Corpo: `{ "archived": true }` ou `false`. Responde `204`.
+
+### `GET /apps/{ref}/deployments`
+
+Leitura. A implantação mais recente, já conferida com a conta de nuvem, ou `null`.
+
+```json
+{ "deployment": { "id": "...", "revision": 2, "status": "running",
+  "url": "https://...run.app", "error": null, "region": "southamerica-east1",
+  "createdAt": "...", "expiresAt": "..." } }
+```
+
+`status`: `deploying`, `running`, `failed` ou `stopped`.
+
+### `POST /apps/{ref}/deployments`
+
+Sessão de quem gerencia o workspace, ou chave com `compute:deploy`. Implanta a revisão atual.
+Responde `202` com a implantação em `deploying`. Só funciona em organização com a prévia
+do runtime; nas demais, e sempre que o plano tiver bloqueios, responde `409` com
+`code: "compute_not_deployable"` e os motivos. Limites da prévia: CPU, até 1 vCPU e 1 GB,
+1 réplica, endereço público, com prazo.
+
+### `POST /apps/{ref}/deployments/stop`
+
+Mesma autenticação. Apaga o serviço na nuvem e encerra a implantação. Responde `204`.

package/docs/cli.md

@@ -0,0 +1,98 @@
+# Referência da CLI `aiuby`
+
+Versão 0.3.0. A CLI fala só com a API da AIUBY: nunca pede nem usa credenciais da AWS ou
+do Google Cloud.
+
+Instalação: `npm install -g https://aiuby.com/cli/aiuby-cli-latest.tgz` (Node.js 20 ou mais novo).
+
+## Autenticação
+
+| Comando | O que faz |
+| --- | --- |
+| `aiuby login [--url <endereço>]` | Lê uma chave de API do terminal (sem eco) ou da entrada padrão, confere com a API e guarda |
+| `aiuby logout` | Apaga a chave deste computador |
+| `aiuby whoami` | Mostra organização, workspace e endereço da API |
+
+- A chave **nunca** é aceita como argumento, para não ficar no histórico do shell.
+- Fica em `~/.config/aiuby/credentials.json`, com permissão `0600`.
+- Uma chave que a API recusa não é guardada.
+- A API precisa ser HTTPS. HTTP só é aceito em `localhost`.
+
+Exemplo sem interação:
+
+```bash
+printf '%s' "$CHAVE" | aiuby login
+```
+
+## Leitura
+
+| Comando | O que faz |
+| --- | --- |
+| `aiuby project list` | O projeto (workspace) da chave em uso |
+| `aiuby apps list` | Aplicações cadastradas no workspace |
+| `aiuby apps status <identificador>` | Detalhe, revisões e plano de uma aplicação |
+| `aiuby capacity list [--provider gcp\|aws]` | Catálogo de hardware. É referência pública: cota, região e preço não foram verificados |
+| `aiuby deploy --dry-run <identificador>` | O plano de implantação, sem criar nada. Sai com código 4 quando há bloqueios |
+
+## Escrita
+
+Exigem uma chave com os escopos "Ler o Compute" e "Gerenciar aplicações do Compute".
+Nenhum destes comandos implanta: eles só registram a aplicação e a configuração.
+
+| Comando | O que faz |
+| --- | --- |
+| `aiuby apps create [arquivo]` | Cadastra a aplicação descrita no `aiuby.toml` (padrão: o do diretório atual), com a revisão r1 |
+| `aiuby apps update [arquivo]` | Grava a configuração do arquivo como nova revisão da aplicação de mesmo `slug`. Sem mudança, não cria revisão. Não altera o nome |
+
+## Implantação (prévia do runtime)
+
+Exigem uma chave com o escopo "Implantar no Compute" e uma organização com a prévia do
+runtime habilitada pela AIUBY. Fora dela, a API recusa com os motivos (código de saída 4).
+
+| Comando | O que faz |
+| --- | --- |
+| `aiuby deploy [--no-wait] <identificador>` | Implanta a revisão atual no Google Cloud e acompanha até ficar em execução (até 3 minutos). Mostra o endereço público e o prazo. Reimplantar troca a revisão no mesmo endereço |
+| `aiuby stop <identificador>` | Para a implantação: o serviço é apagado e o endereço deixa de responder |
+
+Limites da prévia: só CPU, até 1 vCPU e 1 GB, 1 réplica (escala a zero quando ociosa),
+endereço público sem autenticação, prazo de algumas horas. Sem cobrança nesta fase.
+
+## Local
+
+| Comando | O que faz |
+| --- | --- |
+| `aiuby init [template] [diretório]` | Copia um template de partida para um diretório novo ou vazio. Sem argumento, lista os templates |
+| `aiuby config validate [arquivo]` | Valida um `aiuby.toml` (padrão: o do diretório atual). Não usa a rede |
+| `aiuby doctor` | Confere versão do Node.js, credencial, permissão do arquivo e resposta da API |
+
+## Ainda não disponíveis
+
+`run`, `logs`, `scale`, `rollback`, `volumes`, `secrets`
+e `domains` respondem que ainda não estão disponíveis e saem com código 4. Nenhum deles chama a API.
+
+## Opções gerais
+
+| Opção | Efeito |
+| --- | --- |
+| `--json` | Saída em JSON, para scripts |
+| `--help` | Ajuda |
+| `--version` | Versão |
+
+## Variáveis de ambiente
+
+| Variável | Efeito |
+| --- | --- |
+| `AIUBY_TOKEN` | Chave de API. Tem prioridade sobre o arquivo; use em CI |
+| `AIUBY_API_URL` | Endereço da API (padrão `https://aiuby.com`) |
+| `AIUBY_CONFIG_DIR` | Diretório do arquivo de credencial |
+
+## Códigos de saída
+
+| Código | Significado |
+| --- | --- |
+| 0 | Sucesso |
+| 1 | Erro (rede, servidor, `doctor` com falha) |
+| 2 | Uso incorreto |
+| 3 | Não autenticado |
+| 4 | Recusado: recurso indisponível, não encontrado, sem permissão ou plano com bloqueios |
+| 5 | Configuração inválida (no arquivo, ou recusada pela API) |

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@aiuby-ia/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Linha de comando do AIUBY Compute",
+  "type": "module",
+  "bin": {
+    "aiuby": "dist/aiuby.mjs"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild src/main.ts --bundle --platform=node --target=node20 --format=esm --banner:js='#!/usr/bin/env node' --outfile=dist/aiuby.mjs && chmod +x dist/aiuby.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.25.0",
+    "smol-toml": "1.3.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.9",
+    "zod": "4.6.7"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://aiuby.com",
+  "keywords": [
+    "aiuby",
+    "compute",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/fastapi-http/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY main.py .
+# Usuário sem privilégio: o runtime não deve precisar de root.
+RUN useradd --create-home app
+USER app
+EXPOSE 8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

package/templates/fastapi-http/aiuby.toml

@@ -0,0 +1,17 @@
+# Configuração da aplicação no AIUBY Compute. Valide com: aiuby config validate
+name = "Minha API"
+slug = "minha-api"
+
+[config]
+runtime = "container"
+image = "REGISTRO/minha-api:1"
+port = 8080
+
+[config.hardware]
+provider = "any"
+cpu = 1
+memoryMb = 512
+
+[config.scaling]
+minReplicas = 0
+maxReplicas = 2

package/templates/fastapi-http/main.py

@@ -0,0 +1,19 @@
+"""API HTTP mínima. Ponto de partida do template "API HTTP com FastAPI" do AIUBY Compute."""
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI(title="minha-api")
+
+
+class Entrada(BaseModel):
+    texto: str
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.post("/eco")
+def eco(entrada: Entrada) -> dict[str, int | str]:
+    return {"texto": entrada.texto, "caracteres": len(entrada.texto)}

package/templates/fastapi-http/requirements.txt

@@ -0,0 +1,2 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30,<1

package/templates/langgraph-agent/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY main.py .
+# Usuário sem privilégio: o runtime não deve precisar de root.
+RUN useradd --create-home app
+USER app
+EXPOSE 8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

package/templates/langgraph-agent/aiuby.toml

@@ -0,0 +1,17 @@
+# Agente LangGraph por HTTP. Valide com: aiuby config validate
+name = "Agente LangGraph"
+slug = "agente-langgraph"
+
+[config]
+runtime = "container"
+image = "REGISTRO/agente-langgraph:1"
+port = 8080
+
+[config.hardware]
+provider = "any"
+cpu = 1
+memoryMb = 1024
+
+[config.scaling]
+minReplicas = 0
+maxReplicas = 2

package/templates/langgraph-agent/main.py

@@ -0,0 +1,40 @@
+"""Agente mínimo com LangGraph exposto por HTTP. Sem modelo embutido: o nó "responder"
+é onde entra a chamada ao seu modelo (por exemplo, pelo Gateway da AIUBY)."""
+from typing import TypedDict
+
+from fastapi import FastAPI
+from langgraph.graph import END, StateGraph
+from pydantic import BaseModel
+
+
+class Estado(TypedDict):
+    pergunta: str
+    resposta: str
+
+
+def responder(estado: Estado) -> Estado:
+    # Troque por uma chamada ao modelo. Aqui só devolve o que recebeu.
+    return {"pergunta": estado["pergunta"], "resposta": f"Recebi: {estado['pergunta']}"}
+
+
+grafo = StateGraph(Estado)
+grafo.add_node("responder", responder)
+grafo.set_entry_point("responder")
+grafo.add_edge("responder", END)
+agente = grafo.compile()
+
+app = FastAPI(title="agente-langgraph")
+
+
+class Entrada(BaseModel):
+    pergunta: str
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.post("/perguntar")
+def perguntar(entrada: Entrada) -> dict[str, str]:
+    return dict(agente.invoke({"pergunta": entrada.pergunta, "resposta": ""}))

package/templates/langgraph-agent/requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30,<1
+langgraph>=0.2,<1

package/templates/vllm-openai/Dockerfile

@@ -0,0 +1,6 @@
+# Servidor compatível com a API da OpenAI sobre vLLM. O modelo é baixado na subida:
+# escolha um que caiba na memória da GPU pedida e cuja licença permita o seu uso.
+FROM vllm/vllm-openai:latest
+ENV MODEL_ID="Qwen/Qwen2.5-1.5B-Instruct"
+EXPOSE 8080
+ENTRYPOINT ["/bin/sh", "-c", "python3 -m vllm.entrypoints.openai.api_server --model \"$MODEL_ID\" --host 0.0.0.0 --port 8080"]

package/templates/vllm-openai/aiuby.toml

@@ -0,0 +1,21 @@
+# Inferência compatível com OpenAI em GPU. Valide com: aiuby config validate
+name = "Inferência vLLM"
+slug = "inferencia-vllm"
+
+[config]
+runtime = "container"
+image = "REGISTRO/inferencia-vllm:1"
+port = 8080
+
+[config.hardware]
+provider = "gcp"
+cpu = 4
+memoryMb = 16384
+
+[config.hardware.gpu]
+sku = "gcp-cloudrun-l4"
+count = 1
+
+[config.scaling]
+minReplicas = 0
+maxReplicas = 1