presentforme-cli

CLI TypeScript (oclif) per PresentForMe. Consuma il canale /cli/v1 del backend Rails (presentforme-rails). Autenticazione via token utente (account-proxy).

Il comando si chiama presentforme, con alias pfm.

Installazione

npm install -g @bussolabs/presentforme-cli
presentforme --help
pfm --help          # identico

Per lavorare sul repo, node e pnpm sono pinnati in mise.toml (node 24.11.0 + pnpm 11.5.2):

mise install
pnpm install
pnpm build
./bin/run.js --help

Comandi

| Comando | Cosa fa | Endpoint | |---|---|---| | login --token <T> | Verifica il token e lo salva | GET /cli/v1/session | | logout | Rimuove il token salvato (locale, idempotente) | — | | whoami | Mostra l'account autenticato | GET /cli/v1/session | | config list \| get <k> \| set <k> <v> | Legge e scrive la config locale | — | | profile show | Mostra il profilo | GET /cli/v1/profile | | profile update | Aggiorna nome, username, locale, compleanno | PATCH /cli/v1/profile | | gifts list | Elenca i propri regali | GET /cli/v1/gifts | | gifts create | Crea un regalo, anche da URL | POST /cli/v1/gifts (+ /gifts/previews) | | friends list | Elenca i propri amici | GET /cli/v1/friends |

Con --url senza --name, gifts create scrappa prima una bozza da POST /cli/v1/gifts/previews e poi conferma la creazione.

Supportano --json tutti i comandi tranne login e logout, che stampano solo una riga di esito.

pfm login --token TOKEN
pfm whoami --json
pfm gifts list --quiet
pfm gifts create --url https://shop.example.com/prodotto

Configurazione

Persistita in ~/.presentforme/config.json (mode 0600).

| Chiave | Descrizione | Default | |--------|-------------|---------| | serverUrl | URL base del backend | https://presentformenew.bussolarialessio.me | | token | Token utente (mascherato in output) | — |

| Variabile d'ambiente | Effetto | |---|---| | PRESENTFORME_API_URL | Sovrascrive serverUrl | | PRESENTFORME_CONFIG_DIR | Sposta la directory di config (profili multipli, isolamento nei test) |

login verifica il token contro GET /cli/v1/session e lo persiste solo se il backend risolve un account; altrimenti propaga l'errore (es. R401-AUTH-001) senza toccare la config.

Error handling

• Errori locali → codice C{STATUS}-{DOMAIN}-{SEQ} (registry in src/errors/error-codes.ts).
• Errori dal backend (R/G-prefix) → estratti dal body e propagati as-is, mai rimappati.
• Exit code: 0 successo · 1 errore (locale o backend) · 2 errore di utilizzo.

Struttura

src/
  commands/   login · logout · whoami · config · profile/* · gifts/* · friends/*
  errors/     error-codes.ts (registry C-prefix)
  lib/        api-client · auth · config · output · errors · types
test/         lib/* + commands/* (vitest)
opencli.json  manifesto OpenCLI (opencli.org), spedito nel pacchetto

Sviluppo

pnpm build         # tsup → dist/ (ESM)
pnpm typecheck     # tsc --noEmit
pnpm test          # vitest run
./bin/run.js ...   # esegue da dist/