@wolfgang-sfi/praxis-core

CLI de Praxis HR para generar borradores de correo de candidatos y abrirlos en Outlook desktop, sin descargar scripts desde el navegador.

Complementa las opciones de la web:

| Opción web | CLI | |------------|-----| | ZIP descargado | Equivalente local, sin cuarentena de Gatekeeper en Mac | | — | Recomendado en macOS — abre borrador en Outlook |

Instalación (usuarios)

No hace falta instalar nada de forma global. Con Node.js ≥ 18:

npx @wolfgang-sfi/praxis-core --help

npx descarga el paquete, ejecuta el comando y no deja instalación permanente (salvo caché de npx).

Configuración

Recomendado — login por navegador (reutiliza tu sesión web y crea el PAT automáticamente):

npx @wolfgang-sfi/praxis-core auth login
npx @wolfgang-sfi/praxis-core auth whoami

Por defecto apunta a https://praxis-coordinator.vercel.app. Para otra instancia: --api <URL>.

Si ya hay un token válido en el dispositivo, auth login no abre el navegador (usa --force para volver a autorizar).

Alternativa manual (CI o scripts):

npx @wolfgang-sfi/praxis-core auth set-token --api https://praxis-coordinator.vercel.app praxis_…
# o
npx @wolfgang-sfi/praxis-core auth login --token praxis_… --api https://tu-dominio-praxis

El token manual se crea en Mi perfil → Tokens de API (CLI).

Uso habitual

# Menú interactivo: proyecto → posición → candidato
npx @wolfgang-sfi/praxis-core mail draft

# Atajo con ID de candidatura
npx @wolfgang-sfi/praxis-core mail draft --application-id <id>

Archivo de configuración local

| SO | Ruta | |----|------| | macOS / Linux | ~/.config/praxis-hr/config.json | | Windows | %APPDATA%\praxis-hr\config.json |

Variables opcionales: PRAXIS_API_URL, PRAXIS_API_TOKEN (sobrescriben el archivo).

Requisitos

• Node.js ≥ 18 (para npx)
• Cuenta en Praxis HR con token PAT
• macOS: Microsoft Outlook para Mac + permiso de automatización para Terminal
• Windows: Outlook como app predeterminada para .eml

Comandos

Autenticación

npx @wolfgang-sfi/praxis-core auth login [--api <URL>] [--force]
npx @wolfgang-sfi/praxis-core auth set-token --api <URL> <token>
npx @wolfgang-sfi/praxis-core auth login --token <token> [--api <URL>]
npx @wolfgang-sfi/praxis-core auth whoami
npx @wolfgang-sfi/praxis-core auth logout

Correo

npx @wolfgang-sfi/praxis-core mail draft
npx @wolfgang-sfi/praxis-core mail draft --application-id <id>
npx @wolfgang-sfi/praxis-core mail context --application-id <id>
npx @wolfgang-sfi/praxis-core mail draft --save ./borrador.zip
npx @wolfgang-sfi/praxis-core mail draft --no-open

Sin --application-id, menú interactivo (proyecto → posición → candidato). En CI o sin TTY, usa --application-id.

Flujo de mail draft

1. Menú interactivo (opcional): GET /api/clients → posiciones → candidatos.
2. GET /api/applications/:id/mail-context — valida campos y bloqueos.
3. Si faltan datos (Para, asunto, CV Praxis, etc.), abre el detalle del candidato en el navegador y termina con error; complétalos en la web y vuelve a ejecutar el comando.
4. POST /api/applications/:id/generate-mail con delivery: "zip".
5. Descarga del ZIP vía /api/blob.
6. Windows: abre el .eml. macOS: AppleScript embebido en la CLI.

Desarrollo (monorepo)

Código fuente en packages/praxis-hr-cli del repositorio Praxis.

# Desde la raíz del repo
bun install
bun run build:cli
bun run praxis-core --help

# O dentro del paquete
cd packages/praxis-hr-cli
npm run build
npm run praxis-core -- mail draft --no-open

En localhost la web sugiere bun run praxis-core (build local). En producción: npx @wolfgang-sfi/praxis-core.

Publicar en npm (mantenedores)

Importante: publica solo el paquete @wolfgang-sfi/praxis-core, no la raíz del monorepo (praxis-cli).

1. Crear el scope en npm (solo la primera vez)

El error Scope not found significa que la organización @wolfgang-sfi no existe en npmjs.com o tu usuario no es miembro con permiso de publicar.

1. Entra con la cuenta que usarás para publicar (ahora mismo: la que devuelve npm whoami).
2. Crea la organización: npmjs.com/org/create → nombre wolfgang-sfi.
   • Plan Free basta para paquetes públicos con scope.
3. En la org, añade como Owner o Developer a quien vaya a ejecutar npm publish.

Sin este paso, npm publish --access public siempre fallará con 404 en el PUT.

2. Publicar

Automático (GitHub Actions)

Cada push a main que toque packages/praxis-hr-cli/** dispara el workflow .github/workflows/publish-cli.yml. Compara la versión de package.json con la publicada en npm y publica solo si es nueva.

Configuración única (secret en GitHub):

1. En npmjs.com → Access Tokens → Generate New Token → tipo Automation (permiso de publicación en @wolfgang-sfi).
2. En GitHub → repo → Settings → Secrets and variables → Actions → New repository secret.
3. Nombre: NPM_TOKEN. Valor: el token de npm.

Sin ese secret el workflow hace skip del publish o falla en el paso final.

Flujo habitual: bump de versión en package.json + entrada en CHANGELOG.md + push a main. No hace falta npm publish manual.

Manual (local)

Desde la raíz del monorepo:

npm login
npm run publish:cli

O desde este directorio:

cd packages/praxis-hr-cli
npm run build
npm pack --dry-run    # name: @wolfgang-sfi/praxis-core, ~15 kB, bin dist/bin.js
npm publish --access public

El tarball correcto debe mostrar name: @wolfgang-sfi/praxis-core, no praxis-cli.

3. Verificar

Desde fuera del monorepo (o tras publicar), en una carpeta cualquiera:

npx @wolfgang-sfi/praxis-core@latest --help

Si ves sh: praxis-core: command not found:

1. El paquete aún no está en npm — confirma con npm view @wolfgang-sfi/praxis-core version.
2. Estás en la raíz del monorepo — npx no resuelve bien el workspace; usa bun run praxis-core o prueba desde otra carpeta (cd /tmp).
3. Caché rota — npm cache clean --force y repite.

Desde la raíz del repo (desarrollo local): bun run praxis-core, no npx.

Versiones

La CLI tiene versionado independiente de la app web. La versión publicada en npm es la de packages/praxis-hr-cli/package.json.

# Desde la raíz del monorepo
npm run build:cli
npm run version:cli patch   # o minor / major
npm run publish:cli

# O desde el paquete
cd packages/praxis-hr-cli
npm version patch
npm publish --access public

Changelog: CHANGELOG.md.

Estructura

packages/praxis-hr-cli/
  package.json          # name: @wolfgang-sfi/praxis-core
  tsconfig.build.json
  dist/                 # salida compilada (publicada en npm)
  src/
    bin.ts              # bin praxis-core
    client.ts
    commands/
    interactive/
    outlook/

Seguridad

| Riesgo | Mitigación | |--------|------------| | PAT filtrado | Revocación en perfil; HTTPS obligatorio | | Token en disco | chmod 600; auth logout al desinstalar | | Permisos | Mismo ACL que el usuario en la web |

Relación con la app web

Documentación del servidor (Graph, ZIP, env): README.md en la raíz del monorepo.