jarvis-ade

Instale, procure, crie e valide plugins do marketplace do Jarvis ADE direto do terminal. Install, search, scaffold and validate Jarvis ADE marketplace plugins from your terminal.

npx -y jarvis-ade plugins add <handle>/<slug>

Zero dependências de runtime · Node ≥ 20 · MIT Zero runtime dependencies · Node ≥ 20 · MIT

Início rápido (pt-BR)

# 1. procurar (a coluna ID já é o que o "add" aceita)
npx -y jarvis-ade plugins search clickup

# 2. ver detalhes: nota, instalações, versão, repositório
npx -y jarvis-ade plugins info acme/hello-ade

# 3. instalar no app Jarvis ADE (o app precisa estar aberto)
npx -y jarvis-ade plugins add acme/hello-ade
npx -y jarvis-ade plugins add acme/[email protected] --yes      # só se 1.2.0 ainda for a última versão; sem perguntar
npx -y jarvis-ade plugins add acme/hello-ade --dry-run        # só mostra o que seria instalado

# 4. criar e validar o seu plugin
npx -y jarvis-ade plugins init meu-plugin --name "Meu Plugin"
npx -y jarvis-ade plugins validate meu-plugin

Como o add funciona

1. Resolve <handle>/<slug> no registro (GET /v1/marketplace/resolve/:handle/:slug) → nome, versão e origem (npm ou git). O marketplace só serve a última versão aprovada: @versão não é enviado ao registro, apenas confere — se a última versão for outra, o comando recusa e não instala nada. <handle> e <slug> são minúsculos, 3–39 caracteres (letras, números e hífens internos).
2. Baixa o ade.plugin.json do pacote npm (ou do arquivo raw do GitHub) sem instalar nada e mostra as configurações que o plugin vai pedir — e se ele roda um processo em segundo plano.
3. Pede confirmação (a não ser com --yes).
4. Entrega a instalação ao app desktop — a CLI nunca escreve nas pastas de plugins do app, porque o app guarda os metadados no próprio banco de estado e uma cópia crua ficaria invisível.
5. Avisa o registro (POST …/installs, {"source":"cli"}) para o contador de instalações; se isso falhar, o comando não falha.

Se o Jarvis ADE não estiver aberto, o comando termina com código 3 e mostra o caminho manual: Plugins → Importar → npm <pacote> (ou git <url>) e o deep link jarvisade://plugins/install?handle=<handle>&slug=<slug>.

Comandos

| Comando | O que faz | | --- | --- | | plugins add <handle>/<slug>[@versão] [--yes] [--dry-run] [--json] | resolve e instala no app desktop | | plugins search [consulta] [--category c] [--sort s] [--json] | lista o marketplace em tabela. --sort: popular (padrão) · top-rated · recent · trending. --category: integrations · productivity · agents · devtools · data · themes · other. Outro valor → código 2 com a lista válida | | plugins info <handle>/<slug> [--json] | detalhes de um plugin | | plugins init [dir] [--name n] [--id i] [--force] | cria um plugin sem dependências | | plugins validate [dir] [--json] | valida ade.plugin.json + package.json |

Opções globais: --registry <url>, --help, --version. Cores só em terminal e com NO_COLOR ausente.

Variáveis de ambiente

| Variável | Padrão | Uso | | --- | --- | --- | | JARVIS_MARKETPLACE_URL | https://jarvis-license.vidiio.net | registro do marketplace (--registry tem prioridade) | | JARVIS_ADE_BRIDGE_URL + JARVIS_ADE_BRIDGE_TOKEN | — | endereço/token da ponte do app (senão lê o bridge.json) | | JARVIS_NPM_REGISTRY | https://registry.npmjs.org | de onde baixar o pacote para a pré-visualização | | JARVIS_GIT_RAW_BASE | https://raw.githubusercontent.com | idem, para plugins git | | NO_COLOR | — | desliga cores |

bridge.json ({"url": "...", "token": "..."}) fica na pasta de dados do app: Linux ~/.config/J.A.R.V.I.S., macOS ~/Library/Application Support/J.A.R.V.I.S., Windows %APPDATA%\J.A.R.V.I.S.. O token só é enviado para endereços de loopback (127.0.0.1, localhost, ::1).

Códigos de saída

0 ok · 1 erro (plugin não encontrado, app recusou, validação falhou…) · 2 uso incorreto · 3 Jarvis ADE não está aberto.

O que o validate confere

Erros (saída 1): ade.plugin.json fora do schema do host (id kebab-case, versão semver, adapter/effort, tipos de setting string|secret|boolean|number, ids duplicados, caminhos fora do plugin…), arquivos referenciados que não existem, repository do package.json ausente ou que não seja GitHub, files que não inclui o ade.plugin.json (ou o que ele referencia). Avisos: dependencies (o instalador só copia arquivos), scripts preinstall/install/postinstall, palavra-chave jarvis-ade-plugin ausente, versão do package.json diferente da do manifesto. As regras espelham as checagens automáticas do marketplace.

Quick start (English)

npx -y jarvis-ade plugins search clickup          # the ID column is exactly what `add` takes
npx -y jarvis-ade plugins search --sort trending --category devtools   # sort: popular|top-rated|recent|trending
npx -y jarvis-ade plugins info acme/hello-ade
npx -y jarvis-ade plugins add acme/hello-ade      # Jarvis ADE must be running
npx -y jarvis-ade plugins add acme/[email protected] --yes   # only while 1.2.0 is still the latest version
npx -y jarvis-ade plugins add acme/hello-ade --dry-run

npx -y jarvis-ade plugins init my-plugin --name "My Plugin"
npx -y jarvis-ade plugins validate my-plugin

add resolves the plugin through the registry, previews its ade.plugin.json (settings it will ask for, background processes it will run) without installing anything, asks for confirmation, then hands the install to the running desktop app. The CLI never writes into the app's plugin folders (the app keeps plugin metadata in its own state database, so a raw copy would be invisible). If the app is not running the command exits with code 3 and prints the manual route (Plugins → Importar → npm <package> / git <url>) plus the deep link jarvisade://plugins/install?handle=<handle>&slug=<slug>.

The preview is fail-closed. The CLI reads the npm tarball with a strict reader that accepts only what npm pack writes (one gzip member of POSIX ustar files/directories plus pax path/size records) and refuses to guess at anything else: GNU/v7 headers, bad checksums, base-256 or non-octal numbers, links, devices, GNU long names, stray or single zero blocks, data after the end-of-archive marker, duplicate pax keys, and duplicate entry paths (also case-insensitive or Unicode-normalised ones). Long paths written by npm pack are understood: the full 155-byte ustar prefix (as node-tar reads it) and a pax path, which replaces the ustar name and prefix exactly like node-tar's extractor does. A tarball over 30 MB or an ade.plugin.json over 1 MB is treated the same way, because a publisher can pad either to hide the manifest. A tarball like that gets no preview, a red WARNING: no preview line, a stronger confirmation question, and without a terminal it refuses unless you pass --yes. The reason is that the desktop installs with npm install, and node-tar resolves each of those ambiguities differently from a lenient reader, so a preview built from one could show a manifest that is not the one that gets installed.

Exit codes: 0 ok · 1 error · 2 usage · 3 Jarvis ADE not running. See the tables above for commands and environment variables.

Desktop handoff contract

For the desktop app to implement:

discovery   env JARVIS_ADE_BRIDGE_URL + JARVIS_ADE_BRIDGE_TOKEN,
            else bridge.json {"url","token"} in the app's userData dir
request     POST <url>/api/plugins/install
            Authorization: Bearer <token>
            {"source": <resolve source>, "marketplace": {"handle","slug","version"}}
reply       {"ok":true,"data":{"pluginId","name","version"}}
            | {"ok":false,"code","message"}

<resolve source> is {"type":"npm","package","version"} or {"type":"git","url","ref"}, exactly as returned by GET /v1/marketplace/resolve/:handle/:slug.

Development

# from packages/jarvis-ade-cli (uses the repo root's typescript)
node ../../node_modules/typescript/bin/tsc -p tsconfig.json          # build → dist/
node ../../node_modules/typescript/bin/tsc -p tsconfig.test.json --noEmit   # typecheck src + tests
npm test                                                             # compile + node --test
npm pack                                                             # tarball for `npx --yes ./jarvis-ade-x.y.z.tgz`

Tests run against in-process fake servers (registry, npm tarballs, raw GitHub and the desktop bridge) — no network. src/manifest.ts is a hand-written copy of the host manifest schema (packages/shared/src/domain/plugin.ts); when the host schema changes, update it and its tests.

Licença / License

MIT