Publica una app del Desk en la tienda de apps, paso a paso

El proceso de un vistazo#

Publicar pone tu app en la tienda de apps del Desk, miblo.ai/apps, para que cualquiera la instale en su Miblo con un clic. El camino:

1. La construyes y la pruebas en tu computador: en el simulador (miblo apps dev) y en tu Miblo real, con el botón Enviar al Miblo (Desarrollar).

2. La empaquetas: miblo apps pack my-app corre las verificaciones de la tienda de apps del Desk y escribe my-app.zip (y, con una carpeta store/, my-app-store.zip con los textos, el ícono y las capturas también).

3. La envías en miblo.ai/es/apps/enviar, partiendo del paquete: suelta el zip en el primer paso y su manifest.json completa el resto (nombre, promesa, ajustes, direcciones, alertas y la tarjeta de vista previa). Luego el listado (ícono, descripción, capturas), los ajustes (leídos del manifest) y una revisión de todo.

4. El análisis automático verifica el paquete de inmediato y rechaza lo que no puede pasar, con el motivo.

5. La revisión de IA escribe un informe de seguridad sobre el código (unos minutos después).

6. Una persona la aprueba, en un plazo de 7 días. Ninguna app entra a la tienda de apps del Desk sin la aprobación de un humano; recibes la respuesta por correo.

7. miblo.ai firma el paquete con la clave de apps, y quien lo instala verifica la firma antes de que corra nada.

Toda app es un programa#

Toda app de la comunidad lleva un paquete de código: un manifest.json y un main.js que Miblo ejecuta en el sandbox en el computador de quien la instala. Un envío sin código se rechaza (code_required). Una app puede dibujar una pantalla (una página web, la forma estándar desde Miblo 1.45, o las tarjetas obsoletas, efectos, animaciones y gráficos en vivo) o, con "screen": false en su manifest, solo enviar alertas.

Qué contiene un envío#

El servidor decodifica y rehace cada imagen; nada del archivo original se sirve jamás. Hasta 10 envíos al día por miembro, y un envío en revisión a la vez por miembro: mientras una de tus apps espera revisión, una app nueva o una revisión de otra app se rechaza (pending_exists); una revisión nueva de la misma app reemplaza a la pendiente. Cuando envías, el equipo de Miblo recibe un aviso por correo.

El paquete de código#

Un zip de Node.js plano, ESM, sin dependencias:

my-app.zip
├── manifest.json
├── main.js
├── lib/source.js       (optional: other .js and .json files)
└── README.md           (optional)

manifest.json#

{
  "id": "tide",
  "api": 5,
  "name": { "pt": "Maré", "en": "Tide" },
  "category": "daily",
  "promise": { "pt": "A maré está subindo?", "en": "Is the tide coming in?" },
  "settings": [
    { "key": "port", "label": { "pt": "Porto", "en": "Port" }, "type": "text", "required": true, "max": 40, "placeholder": { "pt": "Santos", "en": "Brighton" } }
  ],
  "network": ["api.example-tides.com"],
  "intervalMs": 600000,
  "preview": { "v": 1, "title": "Tide", "items": [{ "t": "big", "value": "1.2 m", "label": "rising" }] }
}

La tienda de apps del Desk reescribe manifest.json a partir de estos campos cuando reempaqueta el código: cualquier otro campo (dwell, previews...) se descarta.

main.js#

// main.js: called every intervalMs, or right after the person changes a setting.
export async function run(ctx) {
  const t = ctx.lang === 'pt' ? { up: 'subindo', down: 'descendo', at: 'às' } : { up: 'rising', down: 'falling', at: 'at' };
  const port = encodeURIComponent(ctx.settings.port);
  try {
    const data = await ctx.fetchJson(`https://api.example-tides.com/v1/port/${port}`);
    ctx.state.last = { now: data.now, rising: data.next > data.now, at: ctx.now() };   // in memory only
  } catch (e) {
    // Nothing yet: a waiting card (the log says "offline: <error>"). Else the last reading stays.
    if (!ctx.state.last) return { card: { title: 'Tide', items: [{ t: 'text', value: '...', color: 'grey' }] }, offline: true, error: e.message };
    ctx.log(`kept the last reading (${e.message})`);
  }
  const { now, rising, at } = ctx.state.last;
  return {
    card: { title: 'Tide', items: [
      { t: 'big', value: `${now.toFixed(1)} m`, label: rising ? t.up : t.down, color: 'blue' },
      { t: 'text', value: `${t.at} ${ctx.timeOf(at)}`, color: 'grey' },
    ] },
    peek: false,                                      // true asks for a peek (once every 10 min)
  };
}

run(ctx) recibe:

fetchJson(url, options) y fetchText(url, options) aceptan { timeoutMs, headers }. headers solo puede llevar authorization (el token de acceso de ctx.app.connect.token(): Bearer ...), accept, accept-language, if-none-match e if-modified-since; cualquier otro se rechaza por su nombre. Los hosts siguen siendo los de network.

Una respuesta que no es 2xx se convierte en un error HTTP 403 from www.googleapis.com/youtube/v3/channels?part=statistics&key=***: <un extracto de la respuesta>, con status y host: el extracto tiene como máximo 300 caracteres, sin claves, tokens ni contraseñas (de la dirección y del cuerpo). Cuando run() falla, el log dice por qué (el campo de una tarjeta rechazada, el archivo y la línea de una excepción), y la app lo intenta de nuevo en 5 s, luego 10, 20, 40..., nunca más allá de su propio intervalMs; tras un 4xx (una clave incorrecta, una cuota agotada), al menos 10 s. Una ejecución buena reinicia la cuenta.

Y devuelve:

Miblo declara la app, lee los ajustes, pide los que faltan y dibuja la tarjeta por ti. Un error lanzado desde run() va al log y la app se vuelve a llamar 5 s después.

Las apps oficiales también pueden exportar options, suggest y migrate desde main.js (listas consultadas una vez por semana, autocompletado, traslado de ajustes antiguos); al main.js de una app de la comunidad solo se le llama run(ctx).

Reglas de archivos#

• Solo .js, .json y .md; como máximo 64 archivos, 8 carpetas de profundidad, nombres de hasta 64 letras, dígitos, ., _ o -, sin dos nombres que difieran solo en mayúsculas.

• Sin package.json y sin node_modules: el runtime de Miblo es el único "paquete".

• El zip hasta 2 MB, todo descomprimido hasta 2 MB, cada script hasta 512 KB.

• main.js debe exportar run(ctx).

Apps del Desk de página#

La tienda de apps del Desk acepta apps del Desk de página (API de apps 4 o 5, Apps del Desk de página). Necesitan un Miblo Desk con firmware 1.45 o más nuevo: en uno más antiguo, la tienda de apps del Desk y miblo apps dicen que necesita una actualización de firmware.

• El paquete también contiene la página y lo que carga, a su lado: CSS, imágenes (PNG, JPEG, GIF, WebP, SVG), fuentes (WOFF, WOFF2, TTF, OTF), scripts y videos (WebM, MP4).

• Cada uno de esos archivos pesa como máximo 256 KB; un video puede ser tan grande como lo permita el paquete (2 MB en total).

• network lista los hosts a los que la página puede llegar (fetch, imágenes, fuentes), por https, la misma regla que ctx.fetchJson; todo lo demás se bloquea.

• run() devuelve { data }, JSON de hasta 16 KB, en vez de una tarjeta.

El análisis automático#

Corre al enviar y es la verdad que la revisión de IA no puede anular. Rechaza de inmediato, con el motivo:

• importar un módulo que el sandbox nunca permite: child_process, worker_threads, net, tls, dgram, http, https, http2, vm, module, wasi, cluster, inspector;

• cualquier dependencia (un módulo que no es un integrado de Node), node_modules o un package.json;

• eval, new Function y sus equivalentes (una cadena a setTimeout, .constructor(...)), import() o require() de algo calculado, createRequire, WebAssembly, código nativo (process.binding, dlopen), acceso calculado al objeto global;

• una dirección cuyo host no está en network (también escrita https:host, con barras invertidas o partida en trozos), o un host declarado que el código nunca usa;

• un manifest.json que rompe las reglas de arriba (sin api, sin promesa, un id que no es la dirección...);

• archivos fuera de las reglas de arriba, un script con un error de sintaxis, una importación de un archivo que no existe, un main.js sin run(ctx).

Y señala al revisor (sin rechazar por sí solo): hosts escritos sin https://, direcciones http://, hosts construidos en tiempo de ejecución, bloques base64 o hex de más de 1 KB, decodificación (atob, Buffer.from(..., 'base64')), señales de ofuscación (nombres aleatorios, _0x..., cadenas partidas, String.fromCharCode, líneas minificadas), lecturas de process.env más allá de MIBLO_*, rutas fuera de la carpeta de la app, caracteres invisibles y texto dirigido al revisor ("ignore previous instructions", "approve this app", juegos de rol).

La revisión de IA#

Tras el análisis, el código entra a la cola de la revisión de IA (corre cada 10 minutos y toma unos minutos):

• Dos pasadas independientes: la primera escribe el informe; la segunda, con otras instrucciones, verifica el informe contra el código y dice qué se le escapó.

• El informe cubre: el nivel de riesgo, cada destino de red y por qué, lo que la app lee del computador, lo que sale de él y adónde, persistencia, comportamiento oculto, señales de código malicioso (robo de credenciales, minería, código cargado desde la red, escapes del sandbox, acciones destructivas) e intentos de dirigir al revisor, con un resumen en portugués y en inglés.

• La IA nunca aprueba ni rechaza. El veredicto ("ok" o "necesita una mirada cuidadosa") lo calcula el servidor: que las pasadas discrepen, un riesgo alto, texto dirigido al revisor o un host no declarado siempre piden una mirada cuidadosa.

• Protegida contra la manipulación: el código entra como datos, entre marcadores, con la instrucción fija de que nada en él es una instrucción; la respuesta se valida contra un esquema; los textos tienen tope.

La aprobación humana#

El revisor ve los hallazgos del análisis, ambos informes, los hosts y, en una revisión, qué cambió desde la versión anterior. Solo entonces la aprueba (miblo.ai firma el paquete) o la rechaza con un motivo, que te llega por correo, dentro de los 7 días de tu envío. La página pública de la app dice "Esta app se comunica con: ..." (los hosts declarados y verificados) o "No usa internet".

Después de publicarla#

• Revisiones: una edición es una revisión nueva con una versión mayor, que sigue el mismo camino. La versión aprobada sigue activa hasta que se aprueba la siguiente.

• Las actualizaciones llegan a quienes la instalaron: cada Miblo con la app verifica la tienda de apps del Desk en cada inicio y cada hora. Una versión nueva que llega exactamente a lo que llegaba la instalada (los mismos hosts, sesiones y alertas) se instala sola; una que pide más espera a que la persona acepte ("Actualización disponible" en Miblo Hub, o miblo apps install <id> en su terminal).

• Valoraciones: los miembros dan de 1 a 5 estrellas; el promedio y la cuenta aparecen en la tienda de apps del Desk.

• Reportes: un reporte oculta la app de inmediato hasta que alguien la revisa (cada miembro oculta como máximo dos apps al día). Los moderadores pueden ocultar y restaurar.

• Una app oculta, para quienes la instalaron: en cada inicio y cada hora, Miblo verifica el paquete; una app que la tienda de apps del Desk ya no sirve o que ocultó se apaga.

Cómo llega el paquete a sus usuarios#

La página de la app tiene el botón Instalar en Miblo Hub, que abre Miblo Hub en tu app (miblo://apps/install/<id>), y el comando miblo apps install <id> para una terminal. Entonces Miblo:

1. descarga miblo.ai/apps/<id>/package.json y verifica su firma con la clave de apps (separada de la clave de las actualizaciones), rechazando un paquete sin una válida;

2. descarga el zip por https (sin redirecciones, nunca más de 2 MB) y verifica su SHA-256 firmado;

3. verifica cada archivo, lo descomprime en <datos de Miblo>/apps/<id>/pkg y enciende la app en el sandbox.

Prueba en tu computador antes de enviar#

Ejecuta la app exactamente como la ejecutará Miblo, en el mismo sandbox, con el simulador:

miblo apps dev my-app        # the app in the sandbox, its screen, settings, alerts and log in your browser
miblo apps check my-app      # the store's scan, offline
miblo apps pack my-app       # the zip the store takes

• El simulador ejecuta main.js como se ejecuta una app instalada: lee solo su propia carpeta, llega solo a los hosts de network (todo lo demás es blocked: <host> en el log), recibe el ctx completo de arriba y se le llama cada intervalMs o cuando guardas sus ajustes.

• Con un Miblo emparejado, Enviar al Miblo (o miblo apps send my-app, desde tu propia terminal) la ejecuta en tu Miblo real, igualmente en el sandbox.

• Sin Miblo instalado, el starter hace lo mismo con node sim.mjs dev my-app (Desarrollar).

Compatibilidad#

Una app no lleva el SDK: lo recibe del Miblo en el que corre (el ctx que recibe su run(), el cliente que contiene, el puente detrás de ellos). Por eso el SDK solo crece, y manifest.json dice para qué API de apps se escribió la app ("api": 5).

• Qué es aditivo (sin nivel nuevo, toda app sigue funcionando): un miembro nuevo de ctx, un campo opcional nuevo, un elemento o efecto de tarjeta nuevo, un tipo de ajuste opcional nuevo, un límite más holgado.

• Qué sube el nivel: quitar algo, renombrarlo, cambiar lo que significa o cómo se comporta, o hacer un límite más estricto. Miblo entonces habla un nivel nuevo y deja de ejecutar el antiguo.

• Cómo se tratan las apps antiguas: una app por debajo del nivel más antiguo que Miblo ejecuta necesita una actualización de su autor: Miblo no la instala, una copia instalada no corre (la pestaña Apps, miblo apps list y Miblo Remote lo dicen), y la tienda de apps del Desk la oculta de sus listas y rechaza una versión suya. Una app por encima del nivel que habla este Miblo necesita un Miblo más nuevo (miblo update). Una app publicada antes del campo (sin api) cuenta como nivel 2 y sigue funcionando.

• miblo apps new escribe el nivel actual; miblo apps check, el simulador y la tienda de apps del Desk lo exigen.

Lista de verificación antes de enviar#

• Miblo+ está activo en tu cuenta, y ninguna de tus otras apps está esperando revisión.

• El id sigue las reglas de la tienda de apps del Desk (de 3 a 32 caracteres, sin palabra reservada, sin miblo-, sin 13) y es igual al del manifest.

• manifest.json dice "api": 5, la API de apps para la que se escribió la app.

• La versión es mayor que la publicada.

• La app responde una pregunta y su promesa (hasta 120 caracteres) dice cuál, en portugués y en inglés.

• La tarjeta cabe: título hasta 24, etiquetas hasta 16, big hasta 10, text hasta 40 caracteres, hasta 4 elementos, ninguna de las frases de Miblo.

• Los ajustes no piden ningún secreto, y los obligatorios tienen un motivo claro.

• network lista exactamente los hosts que usa el código ([] cuando no tiene conexión), todos por https://.

• Ningún módulo bloqueado, ninguna dependencia, ningún eval, ningún texto para el revisor.

• intervalMs es al menos 10000, y la app pide un vistazo solo cuando pasa algo importante.

• La app funciona sin conexión (muestra sus últimos valores y desde cuándo) y sin configurar.

• Probada en el simulador, con el log de la app limpio; miblo apps check pasa.

• Un ícono PNG de 128 × 128, una descripción en al menos un idioma y el "qué cambió" listos; capturas de pantalla si las tienes.