research: investigar publicación del plugin en Decky Plugin Store

[lobinuxsoft]

Descripción

Investigar el proceso de publicación de plugins en la Decky Plugin Store para distribuir el plugin de CapyDeploy a usuarios de Steam Deck.

Motivación

• La store es el canal principal de descubrimiento de plugins Decky
• Sin estar en la store, el plugin es invisible para la mayoría de usuarios
• El plugin ya es funcional (instalación, artwork, borrado, pairing)

Tareas de investigación

• Revisar requisitos de la store (estructura de archivos, metadata, etc.)
• Verificar si hay proceso de review/aprobación
• Comprobar si el monorepo es compatible o si necesita repo separado
• Revisar si hay requisitos de versionado (¿necesita 1.0?)
• Evaluar si el estado actual del plugin es suficiente para publicar

Consideraciones

• El plugin está en v0.3.0 (pre-release)
• Es parte de un monorepo (hub + desktop agent + decky)
• La store puede requerir estructura específica de repositorio
• Publicar implica compromiso de soporte con usuarios reales

Referencias

• https://wiki.deckbrew.xyz (documentación de Decky)
• Discord de Decky Loader (canal #plugin-support)

[lobinuxsoft]

Research: Decky Plugin Store — Findings

1. Submission Process

El proceso es via PR al repo decky-plugin-database:

1. Fork el repo
2. Agregar el plugin como git submodule en plugins/:

   git submodule add https://github.com/you/your-plugin.git plugins/YourPlugin
   cd plugins/YourPlugin && git checkout <tag-o-commit>

3. Abrir PR usando el template plugin_addition
4. CI buildea automáticamente con decky plugin build (Docker)
5. Code review por el Decky Loader Team
6. Testing por un tercero en Steam Deck real (SteamOS Stable/Beta)
7. Merge por un core member

Updates: mismo flow, actualizar el submodule pointer, PR con template plugin_update.

2. Requisito Crítico: Repo Standalone

El plugin DEBE estar en su propio repositorio. La store usa git submodules, que apuntan a la raíz de un repo. No hay mecanismo para apuntar a un subdirectorio de un monorepo.

Opciones:

• Repo standalone (recomendado): extraer el plugin a lobinuxsoft/capydeploy-decky
• git subtree split: desarrollar en monorepo, pushear periódicamente a un repo espejo
• Sparse checkout: no viable con submodules

3. Estructura de Archivos Requerida

plugin-root/
  plugin.json          # REQUERIDO — metadata del plugin
  package.json         # REQUERIDO — npm metadata + version
  pnpm-lock.yaml       # REQUERIDO — lockfileVersion: '9.0' (pnpm v9)
  main.py              # REQUERIDO si usa backend Python
  LICENSE              # REQUERIDO
  rollup.config.js     # Build config frontend
  tsconfig.json
  src/                 # Frontend source
  dist/                # Built frontend (generado)
  py_modules/          # Dependencias Python (ver sección 6)
  defaults/            # Archivos extra (se aplanan al root en el ZIP)
  backend/             # SOLO si hay backend compilado (C/Go/Rust)

4. Schemas de Metadata

plugin.json:

{
  "name": "CapyDeploy",
  "author": "lobinuxsoft",
  "api_version": 1,
  "flags": [],
  "publish": {
    "tags": ["utility", "games"],
    "description": "Deploy games and manage shortcuts on Steam Deck from your PC.",
    "image": "https://raw.githubusercontent.com/.../assets/screenshot.png"
  }
}

package.json (campos clave):

• name: npm-style lowercase ("decky-capydeploy")
• version: semver, debe incrementar en cada update
• scripts.build: lo que ejecuta el CI ("rollup -c")
• pnpm.peerDependencyRules.ignoreMissing: ["react", "react-dom"]

5. Build del CI

El CI usa Docker (ghcr.io/steamdeckhomebrew/builder:latest, Node 20 Alpine + pnpm 9):

1. pnpm i --frozen-lockfile
2. pnpm run build
3. rsync excluyendo src/, __pycache__, node_modules
4. Copia py_modules/ si existe
5. Glob *.py en la raíz
6. Aplana defaults/ al root
7. Crea ZIP con: dist/, *.py, plugin.json, package.json, LICENSE, py_modules/, bin/

IMPORTANTE: El CI NO ejecuta pip install. Solo copia py_modules/ si el directorio existe.

6. Qué Necesita Cambiar en CapyDeploy

Aspecto	Estado Actual	Requerido
Repositorio	Subdirectorio de monorepo	Repo standalone
pnpm-lock.yaml	No existe (tiene bun.lock)	Debe existir, lockfileVersion 9.0
LICENSE	Se copia en build	Debe estar en el root del repo
api_version	2 en plugin.json	Verificar — el template usa 1
*.py en root	✅ Correcto	OK — el CLI los detecta con glob
py_modules/	Se genera en build.sh	Debe estar commiteado o en defaults/
publish en plugin.json	No existe	Agregar para listing en la store

7. Problema de py_modules

El CI no ejecuta pip install, así que las opciones son:

1. Commitear py_modules/ al repo (feo pero es lo que hacen la mayoría de plugins)
2. Poner deps en defaults/ (se aplanan al root en el ZIP)
3. Usar remote_binary en package.json si son grandes

8. Políticas Relevantes

• LLM/AI policy: No aceptan plugins cuya funcionalidad sea LLM-based. No aplica a CapyDeploy (es deployment de juegos).
• Licencia: Si se usó el template (BSD-3-Clause), incluir su notice. CapyDeploy usa AGPL-3.0, que es válido.
• Código: No repos privados, no binarios sin source, no código ofuscado.
• Versionado: Semver, 0.x.x es aceptable.

9. URLs de Referencia

• Plugin Database (PRs)
• Plugin Template
• Decky CLI
• Wiki - Submitting
• Wiki - Review
• CI Workflow

Conclusión

El blocker principal es el monorepo. La store necesita un repo standalone. Todo lo demás (estructura de archivos, Python backend, múltiples .py) es compatible con el CI. Falta: generar pnpm-lock.yaml, agregar campo publish a plugin.json, y resolver el bundling de dependencias Python.

[lobinuxsoft]

Completed. Plugin extracted to standalone repo (lobinuxsoft/decky-capydeploy), v0.5.0 released, store submission PR open (SteamDeckHomebrew/decky-plugin-database#984). Full CI/CD pipeline with automated store submission on release.