puxadinho 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# puxadinho (CLI)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Boxes Linux na nuvem para você e seus agentes.
+
+```sh
+npx puxadinho@latest setup claude   # ou: setup codex
+npm i -g puxadinho                  # instala o comando "puxadinho"
+puxadinho login
+puxadinho create render-ep12
+```
+
+Este pacote é só um lançador: no primeiro uso baixa o binário Go da sua plataforma
+(`puxadinho_<os>_<arch>`, macOS e Linux, arm64 e amd64) da release `v<versão>`, confere o
+sha256 contra o `checksums.txt` que vem dentro deste pacote, guarda em
+`~/.cache/puxadinho/<versão>/` e executa com os mesmos argumentos e código de saída.
+Sinais: Ctrl-C (SIGINT) chega direto ao binário pelo terminal e o lançador não o repete
+(um segundo SIGINT faria a CLI sair sem limpar); SIGTERM e SIGHUP são repassados.
+Requer Node 24 ou mais novo.
+
+## Variáveis
+
+- `PUXADINHO_DOWNLOAD_BASE`: base das releases (padrão
+  `https://github.com/hightech-company/puxadinho/releases/download`; aceita `file://`).
+  O binário é buscado em `<base>/v<versão>/`.
+
+> TODO(release): o repositório acima é o `origin` atual do git; confirme o destino das
+> releases antes de publicar (constante `DEFAULT_BASE` em `bin/puxadinho.js`).
+
+## Códigos de saída
+
+| Código | Significado |
+| --- | --- |
+| 0 | deu certo |
+| 1 | falha geral (inclui `operation_failed`) |
+| 2 | uso errado (flag, argumento; `invalid_argument`, `unknown_field`) |
+| 3 | autenticação (`unauthorized`, `permission_denied`, `missing_scope`) |
+| 4 | não encontrado (`not_found`) |
+| 5 | limite ou plano (`spend_limit_reached`, `quota_exceeded`, `spec_not_allowed`, `box_cooldown`) |
+| 6 | a box não ficou pronta a tempo (`create_timeout`) |
+| 75 | falha passageira, tente de novo (qualquer erro `retryable`, inclui `timeout`) |
+| 125 | falha do `puxadinho run` (infraestrutura, não o seu comando) |
+
+`exec` e `run` saem com o código do próprio comando (sinal = 128+n, estouro de tempo = 124).
+
+Dois códigos existem só na CLI (não vêm da API e não estão no contrato): `timeout` — a espera
+local (`wait`, `jobs wait`, `--timeout`) acabou, mas a operação ou o job continua no servidor —
+e `operation_failed` — uma operação terminou `failed` sem código de erro. Com `--json`, eles
+aparecem no campo `code` como os demais.
+
+## Segurança
+
+- `puxadinho setup claude` usa `claude mcp add --header "Authorization: Bearer <chave>"`, que expõe
+  a chave por instantes na lista de processos da máquina. O Codex guarda a chave em
+  `~/.codex/config.toml` (modo 0600).
+- O `checksums.txt` vem no pacote npm, não da origem do download: um binário trocado na release
+  (ou no meio do caminho) não confere e é descartado.
+- A API padrão é `https://www.usepuxadinho.com.br` (troque com `PUXADINHO_API_URL` ou `--api-url`).
+
+## Publicar uma versão
+
+1. Ajuste `version` em `package.json`.
+2. `pnpm --filter puxadinho build:binaries` gera `dist/v<versão>/puxadinho_*` e o `checksums.txt`
+   (na raiz do pacote, que vai para o npm, e uma cópia em `dist/v<versão>/`)
+   (`go build` com `-ldflags "-X puxadinho.app/go/internal/cli/api.Version=<versão>"`).
+3. Crie a release `v<versão>` com os binários de `dist/v<versão>/`.
+4. `pnpm --filter puxadinho publish` (o pacote leva o `checksums.txt` desses mesmos binários:
+   publique sempre logo depois do build da release).
+
+`dist/` e o `checksums.txt` gerado não vão para o git; o `checksums.txt` vai para o npm.

package/bin/puxadinho.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Executa o binário da CLI desta máquina. Normalmente ele vem no pacote da plataforma
+// (@puxadinho/cli-<os>-<cpu>, dependência opcional que o npm instala só na plataforma certa).
+// Sem ele (ex.: npm com --no-optional), baixa uma vez, confere o sha256 contra o checksums.txt
+// que vem DENTRO deste pacote (nunca o da origem do download) e o executa.
+"use strict";
+const { spawn } = require("node:child_process");
+const { createHash } = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const pkg = require("../package.json");
+const version = pkg.version;
+// TODO(release): troque pelo repositório definitivo das releases (hoje: origin do git).
+const DEFAULT_BASE = "https://github.com/hightech-company/puxadinho/releases/download";
+
+const OS = { darwin: "darwin", linux: "linux" };
+const ARCH = { arm64: "arm64", x64: "amd64" };
+
+function fail(msg, code = 1) {
+  process.stderr.write(`puxadinho: ${msg}\n`);
+  process.exit(code);
+}
+
+async function fetchBuffer(url) {
+  if (url.startsWith("file://")) {
+    return fs.readFileSync(new URL(url));
+  }
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`${url} respondeu ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/** Binário do pacote da plataforma (@puxadinho/cli-<os>-<cpu>), instalado pelo npm como dependência opcional. */
+function platformBinary() {
+  try {
+    return require.resolve(`@puxadinho/cli-${process.platform}-${process.arch}/bin/puxadinho`);
+  } catch {
+    return null;
+  }
+}
+
+async function ensureBinary() {
+  const local = platformBinary();
+  if (local) return local;
+  const goos = OS[process.platform];
+  const goarch = ARCH[process.arch];
+  if (!goos || !goarch) {
+    fail(`plataforma sem suporte: ${process.platform}/${process.arch} (há binários para macOS e Linux, arm64 e x64).`);
+  }
+  const name = `puxadinho_${goos}_${goarch}`;
+  const cacheDir = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "puxadinho", version);
+  const target = path.join(cacheDir, name);
+  if (fs.existsSync(target)) return target;
+
+  // O sha256 esperado vem do pacote npm (gerado no build:binaries da mesma versão):
+  // uma origem de download comprometida não consegue trocar binário e soma juntos.
+  let sums;
+  try {
+    sums = fs.readFileSync(path.join(__dirname, "..", "checksums.txt"), "utf8");
+  } catch {
+    fail("este pacote veio sem checksums.txt; reinstale o puxadinho (npm i -g puxadinho@latest).");
+  }
+  const base = (process.env.PUXADINHO_DOWNLOAD_BASE || DEFAULT_BASE).replace(/\/+$/, "");
+  const root = `${base}/v${version}`;
+  process.stderr.write(`puxadinho: baixando ${name} v${version}…\n`);
+  let bin;
+  try {
+    bin = await fetchBuffer(`${root}/${name}`);
+  } catch (err) {
+    fail(`não consegui baixar o binário (${err.message}). Verifique a rede ou PUXADINHO_DOWNLOAD_BASE.`, 75);
+  }
+  const line = sums.split("\n").map((l) => l.trim().split(/\s+/)).find((p) => p[1] === name || p[1] === `*${name}`);
+  if (!line) fail(`o checksums.txt do pacote não lista ${name}.`);
+  const got = createHash("sha256").update(bin).digest("hex");
+  if (got !== line[0].toLowerCase()) fail(`sha256 de ${name} não confere; o download foi descartado.`);
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, bin, { mode: 0o755 });
+  fs.renameSync(tmp, target);
+  return target;
+}
+
+async function main() {
+  const bin = await ensureBinary();
+  const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+  // Ctrl-C: o terminal já manda SIGINT ao grupo de processos inteiro (o filho
+  // recebe direto). Repassar daria um SEGUNDO SIGINT, que a CLI trata como
+  // "sair já" (o `run` deixaria a box para trás). Aqui só ignoramos o SIGINT e
+  // esperamos o filho sair. SIGTERM/SIGHUP (vindos de `kill`, ou do fim da
+  // sessão) chegam só a nós: esses são repassados.
+  process.on("SIGINT", () => {});
+  for (const sig of ["SIGTERM", "SIGHUP"]) {
+    process.on(sig, () => child.kill(sig));
+  }
+  child.on("error", (err) => fail(`não consegui executar ${bin}: ${err.message}`));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Morreu por sinal: repete o sinal em nós mesmos para o código de saída ser o mesmo.
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+main().catch((err) => fail(err.message));

package/checksums.txt

@@ -0,0 +1,4 @@
+95aabc79a3485810ff19ef30a63a34247c562bf0fba0087299d46f3996d56eef  puxadinho_darwin_arm64
+4b9555625a55de9bf7b69ff9fd2aafa182862abd36942e2cae15551aed74d637  puxadinho_darwin_amd64
+85b066761a6c08d78e74b24ef41d0069520e77d7c84a69cd70f6eba987d86d78  puxadinho_linux_amd64
+7ba1a5024a0ed7ff2ce518081b62f2edda59f3f663b15649b2bc74aac4e8c954  puxadinho_linux_arm64

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "puxadinho",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLI do puxadinho: boxes Linux na nuvem para você e seus agentes.",
+  "license": "SEE LICENSE IN README.md",
+  "type": "commonjs",
+  "bin": {
+    "puxadinho": "bin/puxadinho.js"
+  },
+  "files": [
+    "bin",
+    "checksums.txt",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build:binaries": "node scripts/build-binaries.js"
+  },
+  "optionalDependencies": {
+    "@puxadinho/cli-darwin-arm64": "0.1.0",
+    "@puxadinho/cli-darwin-x64": "0.1.0",
+    "@puxadinho/cli-linux-arm64": "0.1.0",
+    "@puxadinho/cli-linux-x64": "0.1.0"
+  }
+}