viqueue

viqueue es un tablero de tickets minimalista basado en pull para un entorno privado de dogfooding de un solo operador. La CLI es viq; los IDs de tickets tienen el formato ABC-123. v0.4.1 sigue siendo una versión preliminar y no está lista para producción.

Contrato de PoC de emparejamiento

El núcleo HTTP JSON es la única máquina de estados. La autorización es intencionalmente pequeña:

• códigos de emparejamiento de dispositivo de un solo uso y corta duración;

• tipo de dispositivo emparejado fijo: coordinator o worker;

• roles simples utilizados solo como grupos de asignación de trabajadores.

Un coordinador puede crear/editar/archivar tickets, asignar a un dispositivo o rol de trabajador, responder/revisar envíos, emitir/revocar emparejamiento y gestionar roles. Un trabajador puede leer el trabajo asignado, reclamarlo atómicamente, publicar progreso/preguntas/bloqueadores/envíos con valla de reclamación, o liberar su reclamación. Los roles no otorgan permisos de API.

La asignación es la autorización de lanzamiento. Cada reclamación HTTP, CLI y /viq llama al mismo predicado: trabajador emparejado activo, ticket abierto, asignación exacta de dispositivo/rol, sin bloqueador sin resolver y sin reclamación actual. Se prefieren las asignaciones exactas de dispositivo/rol; los tickets elegibles no asignados del grupo libre también pueden reclamarse atómicamente dentro de los límites de proyecto, rol y membresía. No existe la toma de control. No hay acción de inicio, estado Ready almacenado, sistema de alcance genérico ni ruta activa de execution_authorities.

Las reclamaciones permanecen como bloqueos duraderos con valla de generación hasta la liberación o envío explícitos. Las credenciales de reclamación y dispositivo se devuelven solo en la creación/emparejamiento, se almacenan por hash en SQLite y nunca se incluyen en el contexto del ticket/modelo.

Related MCP server: Ticket API MCP Server

Arranque y ejecución

Requiere Node.js 22.

npm test
npm run build
viq-bootstrap --storage ./data/viqueue.sqlite --id coord --name "Coordinator"
node dist/src/server.js --storage=./data/viqueue.sqlite

viq-bootstrap es una acción de instalación local e imprime la primera credencial de coordinador una vez. Proporcione una credencial con --device-token o VIQ_DEVICE_TOKEN:

viq project create ABC --device-token COORDINATOR_CREDENTIAL
viq device pair-code --kind worker --device-token COORDINATOR_CREDENTIAL
viq role create tower-pi --name "Tower Pi" --device-token COORDINATOR_CREDENTIAL
viq role grant tower-worker tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket create ABC "Fix parser" --assignee-role tower-pi --device-token COORDINATOR_CREDENTIAL
viq ticket claim-next --project ABC --device-token WORKER_CREDENTIAL

El tablero del navegador muestra un formulario de emparejamiento cuando no existe un emparejamiento local válido. Los nuevos códigos emitidos por el coordinador vinculan actor, tipo, ID de dispositivo y nombre de dispositivo, por lo que los clientes que solo usan código necesitan únicamente el código de un solo uso; el navegador conserva los campos de ID/nombre para códigos heredados anulables. El tablero verifica /v1/devices/me y almacena solo la credencial devuelta en localStorage['viq.deviceCredential']. Las credenciales inválidas/revocadas se limpian automáticamente, y Desconectar este dispositivo limpia solo el estado local del navegador sin revocar el dispositivo del lado del servidor.

MCP usa VIQ_URL y VIQ_DEVICE_TOKEN y expone vistas de solo lectura de dispositivo/tarea/estado; no puede adquirir ni mutar reclamaciones. Instale el paquete existente en el perfil Pi de un usuario con pi install <Viq package>. Las sesiones Pi posteriores para ese usuario Unix descubren:

/viq PAIRING_CODE [--project KEY]
/viq status
/viq pause|resume|stop

/viq PAIRING_CODE empareja e inicia el trabajador en la sesión Pi visible actual; no hay un comando de trabajador separado ni un ritual de lanzamiento. Antes de cada intento de reclamación, ejecuta visiblemente tools/vault-sync/vault-sync sync en el Vault actual y reclama solo después de que el estado demuestre un commit canónico limpio CURRENT/EQUAL. El servidor VIQ sigue siendo la única autoridad de elegibilidad y reclamación atómica, y el contrato de ticket completo devuelto se inyecta sin cambios con historial saneado. viq_submit sincroniza visiblemente de nuevo y envía la evidencia del operador más el commit publicado exacto solo después de que la publicación tenga éxito; un conflicto, guardia o fallo sin conexión conserva la reclamación con valla para reintentar.

El emparejamiento escribe JSON fuera de los repositorios en ${XDG_CONFIG_HOME:-~/.config}/viq/credential.json, con modo de directorio 0700 y modo de archivo 0600. Las sesiones del mismo usuario Unix lo reutilizan; otros usuarios no. Se admite Pi root ordinario y recibe un archivo solo para root. El sondeo es un temporizador propiedad de esa sesión Pi, detenido al cerrar la sesión, sin daemon ni almacén de ciclo de vida duplicado. VIQ_WORKER_LOCKDOWN=1 explícito conserva el contorno histórico de espacio de trabajo aislado/rechazo de root. Las credenciales permanecen fuera de avisos, estado, resultados de herramientas, argv, entorno y cuerpos de solicitud; el proceso Pi de confianza necesariamente puede leer el archivo de su propio usuario Unix.

Un archivo exacto solo para trabajador se construye desde un HEAD confirmado limpio con npm run bundle:worker -- OUTPUT_DIR. Incluye SOURCE_COMMIT, SOURCE_TREE, la ruta de descubrimiento configurada de package.json y solo la extensión/tiempo de ejecución del trabajador. scripts/install-viq-worker.sh requiere un VIQ_WORKER_ROOT explícito, un commit candidato exacto y un predecesor actual exacto antes de crear una versión de solo lectura y renombrar atómicamente el enlace simbólico current. scripts/rollback-viq-worker.sh acepta solo ese candidato instalado y el predecesor sellado; el predecesor VIQ-15 es 1398284ed89a6cf9395f129483f709e63c009286. Las pruebas y ensayos deben usar una raíz aislada, nunca /opt/viq-worker.

Migración y reversión

La migración hacia adelante crea devices, pairing_codes y device_roles. La tabla antigua execution_authorities se conserva solo para que la reversión a la compilación anterior siga siendo posible; el código candidato no la une, escribe, consume ni expone. La instalación requiere un arranque de coordinador local antes de cambiar los clientes. La reversión restaura el binario anterior y la instantánea de la base de datos juntos; los binarios antiguos aún pueden leer su tabla retenida.

La verificación previa al cambio y la reversión de VIQ-15 no fijan intencionalmente los recuentos de filas de tablas completas. Los tickets, eventos, membresías de roles y otro estado activo no relacionado pueden cambiar legítimamente entre la revisión y el cambio y deben conservarse. La seguridad global de la base de datos se aplica en su lugar mediante la integridad de SQLite, el resumen exacto del esquema, artefactos de reversión autenticados y la igualdad de esquema y recuento de la copia de seguridad consistente con la fuente/SQLite después de que los escritores se detengan. El asistente de reconciliación falla de forma cerrada por separado en las reclamaciones exactas, preguntas abiertas, actores, asignaciones y marcas de tiempo que cambia VIQ-15.

El importador v0.2 sigue siendo explícito y nunca sobrescribe un destino existente. npm run bundle rechaza un árbol sucio, registra la identidad exacta de commit/árbol y crea un archivo local determinista. El instalador escribe un directorio de versión inmutable y cambia atómicamente current, conservando previous; rollback-local.sh lo cambia de vuelta. Cuando VIQ_STORAGE ya existe, la instalación requiere una confirmación explícita sin conexión y usa la API de copia de seguridad de SQLite para capturar y validar el estado confirmado de main/WAL antes de cualquier cambio de puntero. La restauración opcional de reversión primero crea y valida una copia de preservación posterior al candidato consistente con SQLite, luego prepara y valida la instantánea anterior antes de reemplazar la base de datos y eliminar los sidecars obsoletos; también requiere VIQ_RESTORE_STORAGE=1, VIQ_STORAGE y confirmación sin conexión. La desinstalación elimina lanzadores/punteros pero conserva la evidencia de versión y copia de seguridad. Nada aquí publica, despliega o muta el estado activo.

viqueue está licenciado bajo la Apache License 2.0. Consulte SECURITY.md para conocer el modelo de amenazas acotado de PoC privado.