Forge (smolforge)

Forge

Forge tiene dos superficies sobre Cloudflare:

• Repositorios: alojamiento Git, issues, pull requests, Actions, transcripciones y agentes de repositorio.
• Despliegue / Sitios: un SHA enviado exacto se convierte en una vista previa y luego puede convertirse en la aplicación de producción.

Cloudflare sigue siendo el tiempo de ejecución/proveedor. No sustituyas otro producto Git o de alojamiento cuando Forge sea el destino solicitado, y no asumas que una aplicación alojada hereda la autenticación de Forge o Cloudflare Access.

Mantén la tarea con alcance

Clasifica el resultado solicitado antes de cargar más proceso:

• Operación de repositorio: usa Git ordinario más autenticación de Forge.
• Despliegue de aplicación de cliente: usa Forge Deploy y su registro de versiones.
• Reparación de infraestructura de Forge: usa la ruta de versión saludable más pequeña; el plano de control que se repara no necesita desplegar su propia corrección.
• Trabajo solo de código fuente, CLI, documentación, análisis o UI: no agregues puertas de versión de producción a menos que el usuario también haya solicitado un despliegue.

Las retenciones locales de hilo y las versiones no relacionadas no son requisitos previos globales. Aplica solo las comprobaciones que mitiguen un riesgo concreto en la acción solicitada, y detente cuando ese resultado esté probado. Registra hallazgos no relacionados como seguimientos.

Resuelve el comportamiento actual

Forge está evolucionando. Usa la CLI instalada, el repositorio objetivo, la UI/API actual y solo la fuente de primera parte relevante enrutada por el mapa de fuente de Forge. La documentación no prueba la elegibilidad actual de la cuenta, límites o estado de versión.

Inspecciona la sintaxis antes de construir comandos:

sf help
sf commands --json
sf schema --json
sf <comando> --help

Identifica la cuenta, el repositorio, la rama predeterminada y, para Despliegue, la raíz del proyecto. Conserva un remote GitHub existente a menos que el usuario pida reemplazarlo.

Autenticación de repositorio

Un navegador de Forge con sesión iniciada no es una credencial Git local. Usa el flujo de credenciales con alcance de Forge sin exponer su token:

sf auth status
sf auth git-credential <propietario>/<repositorio>
git ls-remote <forge-remote> HEAD

Mantén credential.useHttpPath habilitado. Nunca extraigas tokens del almacenamiento del navegador o del llavero de otra aplicación, ni los pongas en remotes, código fuente, historial del shell o salida. No hagas push forzado, reemplaces origin, cambies la visibilidad o ampíes los ámbitos de las credenciales sin la autorización requerida.

Para migración desde GitHub, usa el flujo de importación actual de Forge. Conserva el gestor de paquetes y maneja Git LFS por separado; importar el historial no copia objetos LFS alojados.

Contrato de Forge Deploy

Forge publica un SHA enviado exacto, no el checkout local. Fuente, compilación, vista previa, publicación del proveedor, activación de producción y verificación en vivo son estados distintos.

Cada proyecto necesita un forgeBuild.ts v1 solo de datos en su raíz configurada. Lee la fuente del manifiesto actual desde el mapa de fuente, luego valida:

npx smolforge deploy check

• Omitir build no ejecuta ningún comando de compilación del repositorio.
• forgeBuild.ts se evalúa estáticamente; no uses configuración ejecutable, importaciones dinámicas ni forge.yml/forge.yaml.
• Una aplicación necesita un punto de entrada HTTP, activos, o ambos. Usa un fallback SPA solo para enrutamiento del lado del navegador.
• .forge/config.json puede mapear proyectos y proponer enlaces; no crea proyectos, aplica estado del proveedor ni otorga autoridad DNS.
• Los enlaces Wrangler importados pueden exponer recursos de producción a las vistas previas.

Crear o habilitar un proyecto, aceptar términos de servicio, promoción, reversión, deshabilitación, rutas y aplicación del proveedor son cambios de estado externos separados. Las URL de vista previa no están listadas y son noindex, no privadas; nunca pongas secretos o datos privados en ellas.

Versión y recuperación

Usa Forge Deploy para aplicaciones de cliente. Para infraestructura de Forge, prefiere el carril canónico mientras esté saludable y sea proporcionado. Wrangler directo es una ruta de operador autorizada cuando ese carril no está disponible, no está saludable, está implicado en el incidente u obstaculiza materialmente la reparación acotada; no es un atajo para evitar el registro de versiones de una aplicación de cliente.

Para una reparación directa de infraestructura, delimita un componente exacto, registra el SHA fuente, las versiones actual y de reversión, y cualquier cambio de migración o enlace; luego verifica tráfico, salud/dependencias y una reproducción. No requieras vistas previas no relacionadas, conciliación del portafolio, prueba exhaustiva o coordinación con tareas que no puedan mutar el mismo componente o esquema.

Antes de reintentar una versión bloqueada, identifica el último estado probado y el diagnóstico dirigido. Verifica el SHA exacto, la raíz del proyecto, la rama y la configuración efectiva de compilación/activos. Reintenta solo cuando el objetivo inmutable y las condiciones de idempotencia estén claras.

Referencias

Usa el mapa de fuente de Forge para cargar solo el documento de primera parte que es dueño de la pregunta actual.