🚀 STRUCT: Generador Automático de Estructuras de Proyectos

Warning

Este proyecto aún está en desarrollo y puede contener errores. Úsalo bajo tu propio riesgo.

📄 Tabla de Contenidos

Introducción
Características
Instalación
Inicio Rápido
Uso
Configuración YAML
Esquema YAML
Desarrollo
Licencia
Financiamiento
Contribuyendo
Agradecimientos
Problemas Conocidos

📦 Introducción

STRUCT es un script potente y flexible diseñado para automatizar la creación de estructuras de proyectos basadas en configuraciones YAML. Admite variables de plantilla, permisos de archivos personalizados, obtención de contenido remoto y múltiples estrategias de manejo de archivos para optimizar tu proceso de configuración de desarrollo.

Está dirigido a desarrolladores, ingenieros DevOps y cualquier persona que quiera automatizar la creación de estructuras de proyectos. Puede usarse para generar código de plantilla, archivos de configuración, documentación y más.

✨ Características

Configuración YAML: Define la estructura de tu proyecto en un simple archivo YAML.
Variables de Plantilla: Usa marcadores de posición en tu configuración y reemplázalos con valores reales en tiempo de ejecución. También admite filtros personalizados de Jinja2 y modo interactivo para completar las variables.
Permisos de Archivos Personalizados: Establece permisos personalizados para tus archivos directamente desde la configuración YAML.
Obtención de Contenido Remoto: Incluye contenido de archivos remotos especificando sus URLs.
Estrategias de Manejo de Archivos: Elige entre múltiples estrategias (sobrescribir, omitir, añadir, renombrar, respaldar) para gestionar archivos existentes.
Ejecutar en Seco: Previsualiza las acciones sin hacer cambios en tu sistema de archivos.
Validación de Configuración: Asegura que tu configuración YAML es válida antes de ejecutar el script.
Registro Detallado: Obtén registros detallados de las acciones del script para una fácil depuración y monitoreo.

🛠️ Instalación

Usando pip

Puedes instalar STRUCT usando pip:

pip install git+https://github.com/httpdss/struct.git

Desde el código fuente

Alternativamente, puedes clonar el repositorio e instalarlo localmente. Consulta la sección Desarrollo para más detalles.

Usando Docker

Puedes usar la imagen de Docker para ejecutar el script sin instalarlo en tu sistema. Consulta la sección Inicio Rápido para más detalles.

🐳 Inicio Rápido

Inicio Rápido Usando Docker

Crea un archivo de configuración YAML para la estructura de tu proyecto. Consulta una configuración de ejemplo aquí.
Ejecuta el siguiente comando para generar la estructura del proyecto:

docker run \
  -v $(pwd):/workdir \
  -u $(id -u):$(id -g) \
  ghcr.io/httpdss/struct:main \
  /workdir/example/structure.yaml \
  /workdir/example_output

Inicio Rápido Usando Docker Alpine

Para pruebas, puedes ejecutar un contenedor Docker de Alpine e instalar el script dentro de él:

docker run -it --entrypoint="" python:3.10-alpine sh -l

Dentro del contenedor:

apk add python-pip git vim
pip install git+https://github.com/httpdss/struct.git
mkdir example
cd example/
touch structure.yaml
vim structure.yaml # copia el contenido de la carpeta de ejemplo
struct structure.yaml .

📝 Uso

Ejecuta el script con el siguiente comando usando uno de los siguientes subcomandos:

generate: Genera la estructura del proyecto basada en la configuración YAML.
validate: Valida la configuración YAML para asegurarte de que sea válida.
info: Muestra información sobre el script y sus dependencias.
list: Lista las estructuras disponibles.

Para más información, ejecuta el script con la opción -h o --help (esto también está disponible para cada subcomando):

struct -h

Ejemplo Simple

struct generate terraform-module ./mi-modulo-terraform

Ejemplo Más Completo

struct generate \
  --log=DEBUG \
  --dry-run \
  --vars="project_name=MiProyecto,author_name=JuanPerez" \
  --backup=/ruta/al/respaldo \
  --file-strategy=rename \
  --log-file=/ruta/al/archivo_de_registro.log \
  terraform-module \
  ./mi-modulo-terraform

📄 Configuración YAML

Aquí tienes un ejemplo de un archivo de configuración YAML:

structure:
  - README.md:
      content: |
        # {{@ project_name @}}
        This is a template repository.
  - script.sh:
      permissions: '0777'
      content: |
        #!/bin/bash
        echo "Hello, {{@ author_name @}}!"
  - LICENSE:
      file: https://raw.githubusercontent.com/nishanths/license/master/LICENSE
  - archivo_remoto.txt:
      file: file:///ruta/al/archivo/local.txt
  - archivo_github.py:
      file: github://owner/repo/branch/path/to/file.py
  - archivo_github_https.py:
      file: githubhttps://owner/repo/branch/path/to/file.py
  - archivo_github_ssh.py:
      file: githubssh://owner/repo/branch/path/to/file.py
  - archivo_s3.txt:
      file: s3://bucket_name/key
  - archivo_gcs.txt:
      file: gs://bucket_name/key
  - src/main.py:
      content: |
        print("Hello, World!")
folders:
  - .devops/modules/mod1:
      struct: terraform/module
  - .devops/modules/mod2:
      struct: terraform/module
      with:
        module_name: mymod2
  - ./:
      struct:
        - docker-files
        - project/go
variables:
  - project_name:
      description: "The name of the project"
      default: "MyProject"
      type: string
  - author_name:
      description: "The name of the author"
      type: string
      default: "John Doe"

Variables de plantilla

Puedes usar variables de plantilla en tu archivo de configuración encerrándolas entre {{@ y @}}. Por ejemplo, {{@ project_name @}} será reemplazado con el valor de la variable project_name en tiempo de ejecución. Si las variables no se proporcionan en la línea de comandos, se solicitarán interactivamente.

Si necesitas definir bloques, puedes usar la notación de inicio de bloque {%@ y la notación de final de bloque %@}.

Para definir comentarios, puedes usar la notación de inicio de comentario {#@ y la notación de fin de comentario @#}.

Variables de plantilla predeterminadas

file_name: El nombre del archivo que se está procesando.
file_directory: El nombre del directorio del archivo que se está procesando.

Variables de plantilla interactivo

Si no proporcionas todas las variables en la línea de comandos, se solicitarán interactivamente.

La struct definida debe incluir las variables en una seccion de variables con la siguiente estructura:

variables:
  - variable_name:
      description: "Descripción de la variable"
      type: string
      default: "Valor predeterminado"

como puedes ver, cada variable debe tener una descripción, un tipo y un valor predeterminado (opcional). Este valor predeterminado se usará si no se proporciona la variable en la línea de comandos.

Filtros personalizados de Jinja2

`latest_release`

Este filtro obtiene la versión más reciente de una release en un repositorio de GitHub. Toma el nombre del repositorio como argumento.

structure:
  - README.md:
      content: |
        # MyProject
        Latest release: {{@ "httpdss/struct" | latest_release @}}

Esto utiliza PyGithub para obtener la última release del repositorio, por lo que configurar la variable de entorno GITHUB_TOKEN te dará acceso a repositorios privados.

Si ocurre un error en el proceso, el filtro devolverá LATEST_RELEASE_ERROR.

NOTA: puedes usar este filtro para obtener la última versión de un proveedor de Terraform. Por ejemplo, para obtener la última versión del proveedor aws, puedes usar {{@ "hashicorp/terraform-provider-aws" | latest_release @}} o el proveedor de datadog {{@ "DataDog/terraform-provider-datadog" | latest_release @}}.

`slugify`

Este filtro convierte una cadena en un slug. Toma un argumento opcional para especificar el carácter separador (el valor predeterminado es -).

structure:
  - README.md:
      content: |
        # {{@ project_name @}}
        This is a template repository.
        slugify project_name: {{@ project_name | slugify @}}

`default_branch`

Este filtro obtiene el nombre de la rama predeterminada de un repositorio de GitHub. Toma el nombre del repositorio como argumento.

structure:
  - README.md:
      content: |
        # MyProject
        Default branch: {{@ "httpdss/struct" | default_branch @}}

Cláusula `with`

La cláusula with te permite pasar variables adicionales a estructuras anidadas. Estas variables se fusionarán con las variables globales y se pueden usar dentro de la estructura anidada.

Ejemplo:

folders:
  - .devops/modules/mod1:
      struct: terraform/module
  - .devops/modules/mod2:
      struct: terraform/module
      with:
        module_name: mymod2

📝 Esquema YAML

Para asegurar que tus archivos de configuración YAML cumplan con la estructura esperada, puedes usar el esquema JSON proporcionado. Esto ayuda a validar tus archivos YAML y proporciona autocompletado en editores compatibles como VSCode.

Configuración en VSCode

Instala la extensión YAML para VSCode.
Añade la siguiente configuración a los ajustes de tu espacio de trabajo (.vscode/settings.json):

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/httpdss/struct/refs/heads/main/struct-schema.json": ".struct.yaml"
  }
}

Esta configuración asociará el esquema JSON con todos los archivos .struct.yaml en tu espacio de trabajo, proporcionando validación y autocompletado.

🔄 Script de Disparador de GitHub

El script github-trigger.py es una utilidad diseñada para activar el flujo de trabajo run-struct en todos los repositorios privados de una organización de GitHub que cumplan con ciertos criterios. Este script es especialmente útil para automatizar tareas en múltiples repositorios.

📋 Características

Filtra repositorios por un tema específico (por ejemplo, struct-enabled).
Verifica la existencia de un archivo .struct.yaml en la rama predeterminada del repositorio.
Comprueba la presencia del archivo de flujo de trabajo run-struct en .github/workflows/.
Activa el evento de despacho del flujo de trabajo en los repositorios elegibles.

🚀 Uso

Para usar el script, asegúrate de cumplir con los siguientes requisitos:

Un token de acceso personal de GitHub válido con los permisos necesarios (configurado como la variable de entorno GITHUB_TOKEN).
La biblioteca PyGithub instalada (pip install PyGithub).

Ejecuta el script con el siguiente comando:

python3 scripts/github-trigger.py <organización> <tema>

Argumentos

<organización>: El nombre de la organización de GitHub.
<tema>: El tema para filtrar los repositorios (por ejemplo, struct-enabled).

Ejemplo

export GITHUB_TOKEN=tu_token_de_acceso_personal
python3 scripts/github-trigger.py mi-org struct-enabled

🛠️ Cómo Funciona

El script se conecta a la API de GitHub utilizando el token proporcionado.
Itera a través de todos los repositorios privados de la organización especificada.
Para cada repositorio:
- Verifica si el repositorio tiene el tema especificado.
- Comprueba la existencia de un archivo .struct.yaml en la rama predeterminada.
- Confirma la presencia del archivo de flujo de trabajo run-struct.
- Activa el evento de despacho del flujo de trabajo si se cumplen todas las condiciones.

⚠️ Notas

Asegúrate de configurar la variable de entorno GITHUB_TOKEN antes de ejecutar el script.
El token debe tener permisos suficientes para acceder a repositorios privados y activar flujos de trabajo.
Los errores durante la ejecución (por ejemplo, archivos faltantes o permisos insuficientes) se registrarán en la consola.

👩‍💻 Desarrollo

Para comenzar con el desarrollo, sigue estos pasos:

Clona el repositorio
Crea un entorno virtual

python3 -m venv .venv
source .venv/bin/activate

Instala las dependencias

pip install -r requirements.txt
pip install -r requirements.dev.txt

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

💰 Financiamiento

Si encuentras este proyecto útil, considera apoyarlo a través de donaciones: patreon/structproject

🤝 Contribuyendo

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request.

🙏 Agradecimientos

Un agradecimiento especial a todos los contribuyentes que hicieron posible este proyecto.

🐞 Problemas Conocidos

TBD

Files

README.es.md

Latest commit

History