Desarrollo de plugins

Inicio rápido

Un paquete es un archivo ZIP con esta estructura:

my-plugin/
├── manifest.json
├── dist/
│   └── plugin.js
└── media/
    ├── icon.png
    └── screenshot.png

1. Crea manifest.json

El backend requiere los campos de identidad y verifica que el archivo de entrada exista en el paquete. Crea tu perfil de publisher antes de empaquetar el plugin y copia exactamente su ID, nombre visible y descripción en el manifiesto. Se rechazan los paquetes que no coincidan con el publisher de la cuenta.

{
  "schemaVersion": 2,
  "id": "publisher.example",
  "publisherId": "publisher-object-id-from-publish-page",
  "publisher": {
    "displayName": "Example Publisher",
    "description": "Tools and integrations for the DELG Code IDE."
  },
  "name": "Example Plugin",
  "version": "1.0.0",
  "entry": "dist/plugin.js",
  "icon": "media/icon.png",
  "images": ["media/overview.png", "media/settings.png"],
  "engines": { "delgIde": ">=0.17.2" },
  "capabilities": [
    "commands",
    "agent-events",
    "workspace-read",
    "workspace-list",
    "status",
    "status-bar"
  ],
  "contributes": {
    "commands": [{
      "command": "publisher.example.run",
      "title": "Example: Run"
    }],
    "statusBarItems": [{
      "id": "publisher.example.status",
      "text": "Example",
      "tooltip": "Example plugin status"
    }]
  },
  "source": {
    "repository": "https://github.com/your-publisher/example-plugin",
    "commit": "0123456789abcdef0123456789abcdef01234567"
  }
}

capabilities y contributes describen el paquete para el marketplace y los revisores de certificación. Los paquetes schema-v2 usan un vocabulario cerrado de capacidades; las comprobaciones de ejecución validan el certificado firmado y la capacidad declarada. Las capacidades sensibles también requieren aprobación en el primer uso.

2. Escribe el punto de entrada

El módulo de entrada debe exportar una función de activación predeterminada. El IDE la llama con la API delg.

export default function activate(delg) {
  delg.registerCommand(
    "publisher.example.run",
    "Example: Run",
    async () => {
      const root = delg.workspace.root || "(no workspace)"
      await delg.ui.setStatus("Running in " + root)
      await delg.ui.showMessage("Example plugin is active")
      const text = await delg.workspace.readFile("README.md")
      console.log(text.length)
      try {
        const files = await delg.workspace.listFiles("")
        await delg.ui.setStatus("Workspace entries: " + files.length)
      } catch {
        // workspace.listFiles requires Verified certification or higher
      }
    }
  )

  try {
    const registration = delg.ui.registerStatusBarItem("publisher.example.status", "Example", "Example plugin status")
    void Promise.resolve(registration).catch((error) => console.warn("Status item unavailable", error))
  } catch {
    // Status bar items require Trusted UI certification or higher
  }

  return delg.onAgentEvent((event) => {
    if (event.type === "done") {
      void Promise.resolve(delg.ui.setStatus("Agent turn finished")).catch(() => undefined)
    }
  })
}

Certificación y aislamiento

Todos los paquetes del marketplace se verifican mediante certificados. Los paquetes schema-v2 se ejecutan en un iframe aislado en todos los niveles; los niveles superiores solo amplían el límite de capacidades intermediadas. El acceso directo al renderer se conserva para la compatibilidad heredada de Full Host schema-v1 y requiere una acción de confianza explícita.

El motor actual permite escribir en el espacio de trabajo desde Verified. Si un plugin solo necesita leer archivos, solicita certificación Community.

Servicios administrados de schema-v2

Usa "schemaVersion": 2 para plugins nuevos. El código schema-v2 se ejecuta en el iframe aislado y solicita servicios del host mediante capacidades declaradas. local-static-server ofrece un servidor de bucle local administrado por el IDE sin conceder acceso a Node.js, shell ni sockets sin procesar.

{
  "schemaVersion": 2,
  "capabilities": ["commands", "workspace-watch", "editor-read", "local-static-server", "open-external"]
}

Contribuciones del manifiesto

Declara capacidades e interfaz en contributes; el manifiesto se valida al subirlo y en cada activación. Define engines.delgIde con la versión mínima del IDE; las versiones incompatibles quedan instaladas pero desactivadas con una explicación.

• Las vistas de la barra lateral, menús, atajos y diagnósticos requieren certificación Trusted UI.
• Las declaraciones de configuración tienen tipos, son locales del dispositivo, globales y nunca secretas; por sí solas no elevan la certificación sobre Community.
• Las vistas solo contienen datos de árbol declarativos. No se exponen HTML, CSS, red ni webviews controladas por plugins.
• Cada id y clave de configuración aportados deben llevar el prefijo del id del plugin; builtin.* está reservado.

Lista de publicación

1. Crea tu perfil de publisher. Cada cuenta puede tener un publisher.
2. Copia el ID y los metadatos del publisher en manifest.json y compila el paquete .delg-plugin.
3. Declara el repositorio de origen exacto y el commit completo en manifest.json; el marketplace los obtiene del paquete. Un origen que no coincida es un fallo de certificación, no un bypass técnico.
4. Los paquetes compatibles con Community se publican de inmediato sin clave de firma del publisher.
5. Para obtener más acceso, configura tu clave Ed25519 de un solo uso en Seguridad del publisher. La carga firma localmente el paquete final y envía la solicitud de certificación.
6. Todos los paquetes se escanean. Las versiones Community limpias se publican automáticamente; las advertencias y accesos elevados permanecen privados hasta la revisión.
7. Las capacidades sensibles de schema-v2 solicitan aprobación en el primer uso. Solo la activación heredada Full Host de schema-v1 requiere confianza del renderer directo.

Reglas de seguridad

• Los paquetes deben contener un manifest.json raíz y una ruta de entrada segura.
• Las rutas opcionales icon e images deben apuntar a archivos PNG, JPEG, GIF o WebP del paquete. Incluye hasta cinco imágenes de galería de 2 MB como máximo.
• Los paquetes están limitados a 25 MB, 500 archivos y 100 MB de tamaño expandido.
• Se rechazan módulos nativos, WebAssembly y node_modules incluidos.
• El scanner v5 rechaza rutas inseguras, cargas ejecutables o nativas, excesos de tamaño, commits inválidos y escaneos incompletos. Comprueba secretos posibles, evaluación dinámica, acceso remoto o al runtime del host, capacidades no declaradas y ofuscación; las advertencias requieren revisión manual con evidencia.
• También se analizan los módulos JavaScript: la evaluación dinámica, APIs sensibles y cargas nombradas por valores de runtime se detectan por estructura. Un archivo que no se puede analizar se informa en vez de omitirse.
• El scanner busca patrones. Una ofuscación decidida puede evadirlo, así que un escaneo limpio solo significa que no coincidió ningún patrón. La certificación depende de la revisión humana posterior.
• Los paquetes Trusted UI y Full Host deben incluir código fuente revisable. Los bundles minificados o generados se rechazan porque el revisor no puede certificar código ilegible.
• El bundling sigue permitido; solo se rechaza la minificación. Community y Verified reciben advertencia, nunca rechazo, por este motivo.
• El IDE verifica el resumen SHA-256, el certificado y el feed de revocación del artefacto antes de cargarlo.
• Los certificados del marketplace los emite DELG tras la certificación automática o humana; las claves del publisher solo prueban quién firmó el artefacto.
• Trusted UI y Full Host requieren dos revisores distintos y ningún revisor puede revisar su propio publisher. El modo normal solo carga paquetes certificados por DELG; los plugins locales sin firma se limitan al Modo desarrollador.