{"id":14985575,"url":"https://github.com/httpdss/struct","last_synced_at":"2025-04-11T22:02:26.246Z","repository":{"id":248437097,"uuid":"827469347","full_name":"httpdss/struct","owner":"httpdss","description":"STRUCT simplifies project organization by creating consistent file and folder structures tailored to your specific needs. Enhance productivity and maintain uniformity across all your projects with this powerful and flexible tool.","archived":false,"fork":false,"pushed_at":"2025-04-10T13:29:19.000Z","size":11858,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T14:52:19.482Z","etag":null,"topics":["automation","cli-tool","developer-tool","developer-tools","devops","devops-tools","file-structure","generator","project-setup","projects","python","python-project","scaffolding","struct","tools","yaml"],"latest_commit_sha":null,"homepage":"https://httpdss.github.io/struct/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/httpdss.png","metadata":{"files":{"readme":"README.es.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"structproject","custom":["https://www.paypal.me/httpdss"]}},"created_at":"2024-07-11T17:51:20.000Z","updated_at":"2025-04-10T13:29:22.000Z","dependencies_parsed_at":"2024-08-18T22:33:02.625Z","dependency_job_id":"c47ad281-5a58-4ab0-be70-c8fa81237908","html_url":"https://github.com/httpdss/struct","commit_stats":{"total_commits":74,"total_committers":1,"mean_commits":74.0,"dds":0.0,"last_synced_commit":"80dceb03fe8ab225f8dee968d1de8e78541f770f"},"previous_names":["httpdss/struct"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httpdss%2Fstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httpdss%2Fstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httpdss%2Fstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httpdss%2Fstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/httpdss","download_url":"https://codeload.github.com/httpdss/struct/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248487710,"owners_count":21112188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli-tool","developer-tool","developer-tools","devops","devops-tools","file-structure","generator","project-setup","projects","python","python-project","scaffolding","struct","tools","yaml"],"created_at":"2024-09-24T14:11:14.042Z","updated_at":"2025-04-11T22:02:26.220Z","avatar_url":"https://github.com/httpdss.png","language":"Python","readme":"# 🚀 STRUCT: Generador Automático de Estructuras de Proyectos\n\n[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/httpdss/struct/blob/master/README.md) [![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/httpdss/struct/blob/master/README.es.md)\n\n![Banner de Struct](extras/banner.png)\n\n\u003e [!WARNING]\n\u003e Este proyecto aún está en desarrollo y puede contener errores. Úsalo bajo tu propio riesgo.\n\n## 📄 Tabla de Contenidos\n\n- [Introducción](#-introducción)\n- [Características](#-características)\n- [Instalación](#instalación)\n  - [Usando pip](#usando-pip)\n  - [Desde el código fuente](#desde-el-código-fuente)\n  - [Usando Docker](#usando-docker)\n- [Inicio Rápido](#-inicio-rápido)\n- [Uso](#-uso)\n- [Configuración YAML](#-configuración-yaml)\n- [Esquema YAML](#-esquema-yaml)\n- [Desarrollo](#-desarrollo)\n- [Licencia](#-licencia)\n- [Financiamiento](#-financiamiento)\n- [Contribuyendo](#-contribuyendo)\n- [Agradecimientos](#-agradecimientos)\n- [Problemas Conocidos](#-problemas-conocidos)\n\n## 📦 Introducción\n\nSTRUCT 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.\n\nEstá 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.\n\n## ✨ Características\n\n- **Configuración YAML**: Define la estructura de tu proyecto en un simple archivo YAML.\n- **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.\n- **Permisos de Archivos Personalizados**: Establece permisos personalizados para tus archivos directamente desde la configuración YAML.\n- **Obtención de Contenido Remoto**: Incluye contenido de archivos remotos especificando sus URLs.\n- **Estrategias de Manejo de Archivos**: Elige entre múltiples estrategias (sobrescribir, omitir, añadir, renombrar, respaldar) para gestionar archivos existentes.\n- **Ejecutar en Seco**: Previsualiza las acciones sin hacer cambios en tu sistema de archivos.\n- **Validación de Configuración**: Asegura que tu configuración YAML es válida antes de ejecutar el script.\n- **Registro Detallado**: Obtén registros detallados de las acciones del script para una fácil depuración y monitoreo.\n\n## 🛠️ Instalación\n\n### Usando pip\n\nPuedes instalar STRUCT usando pip:\n\n```sh\npip install git+https://github.com/httpdss/struct.git\n```\n\n### Desde el código fuente\n\nAlternativamente, puedes clonar el repositorio e instalarlo localmente. Consulta la sección [Desarrollo](#-desarrollo) para más detalles.\n\n### Usando Docker\n\nPuedes usar la imagen de Docker para ejecutar el script sin instalarlo en tu sistema. Consulta la sección [Inicio Rápido](#-inicio-rápido) para más detalles.\n\n## 🐳 Inicio Rápido\n\n### Inicio Rápido Usando Docker\n\n1. Crea un archivo de configuración YAML para la estructura de tu proyecto. Consulta una configuración de ejemplo [aquí](./example/structure.yaml).\n2. Ejecuta el siguiente comando para generar la estructura del proyecto:\n\n```sh\ndocker run \\\n  -v $(pwd):/workdir \\\n  -u $(id -u):$(id -g) \\\n  ghcr.io/httpdss/struct:main \\\n  /workdir/example/structure.yaml \\\n  /workdir/example_output\n```\n\n### Inicio Rápido Usando Docker Alpine\n\nPara pruebas, puedes ejecutar un contenedor Docker de Alpine e instalar el script dentro de él:\n\n```sh\ndocker run -it --entrypoint=\"\" python:3.10-alpine sh -l\n```\n\nDentro del contenedor:\n\n```sh\napk add python-pip git vim\npip install git+https://github.com/httpdss/struct.git\nmkdir example\ncd example/\ntouch structure.yaml\nvim structure.yaml # copia el contenido de la carpeta de ejemplo\nstruct structure.yaml .\n```\n\n## 📝 Uso\n\nEjecuta el script con el siguiente comando usando uno de los siguientes subcomandos:\n\n- `generate`: Genera la estructura del proyecto basada en la configuración YAML.\n- `validate`: Valida la configuración YAML para asegurarte de que sea válida.\n- `info`: Muestra información sobre el script y sus dependencias.\n- `list`: Lista las estructuras disponibles.\n\nPara más información, ejecuta el script con la opción `-h` o `--help` (esto también está disponible para cada subcomando):\n\n```sh\nstruct -h\n```\n\n### Ejemplo Simple\n\n```sh\nstruct generate terraform-module ./mi-modulo-terraform\n```\n\n### Ejemplo Más Completo\n\n```sh\nstruct generate \\\n  --log=DEBUG \\\n  --dry-run \\\n  --vars=\"project_name=MiProyecto,author_name=JuanPerez\" \\\n  --backup=/ruta/al/respaldo \\\n  --file-strategy=rename \\\n  --log-file=/ruta/al/archivo_de_registro.log \\\n  terraform-module \\\n  ./mi-modulo-terraform\n\n```\n\n## 📄 Configuración YAML\n\nAquí tienes un ejemplo de un archivo de configuración YAML:\n\n```yaml\nstructure:\n  - README.md:\n      content: |\n        # {{@ project_name @}}\n        This is a template repository.\n  - script.sh:\n      permissions: '0777'\n      content: |\n        #!/bin/bash\n        echo \"Hello, {{@ author_name @}}!\"\n  - LICENSE:\n      file: https://raw.githubusercontent.com/nishanths/license/master/LICENSE\n  - archivo_remoto.txt:\n      file: file:///ruta/al/archivo/local.txt\n  - archivo_github.py:\n      file: github://owner/repo/branch/path/to/file.py\n  - archivo_github_https.py:\n      file: githubhttps://owner/repo/branch/path/to/file.py\n  - archivo_github_ssh.py:\n      file: githubssh://owner/repo/branch/path/to/file.py\n  - archivo_s3.txt:\n      file: s3://bucket_name/key\n  - archivo_gcs.txt:\n      file: gs://bucket_name/key\n  - src/main.py:\n      content: |\n        print(\"Hello, World!\")\nfolders:\n  - .devops/modules/mod1:\n      struct: terraform/module\n  - .devops/modules/mod2:\n      struct: terraform/module\n      with:\n        module_name: mymod2\n  - ./:\n      struct:\n        - docker-files\n        - project/go\nvariables:\n  - project_name:\n      description: \"The name of the project\"\n      default: \"MyProject\"\n      type: string\n  - author_name:\n      description: \"The name of the author\"\n      type: string\n      default: \"John Doe\"\n```\n\n### Variables de plantilla\n\nPuedes 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.\n\nSi necesitas definir bloques, puedes usar la notación de inicio de bloque `{%@` y la notación de final de bloque `%@}`.\n\nPara definir comentarios, puedes usar la notación de inicio de comentario `{#@` y la notación de fin de comentario `@#}`.\n\n#### Variables de plantilla predeterminadas\n\n- `file_name`: El nombre del archivo que se está procesando.\n- `file_directory`: El nombre del directorio del archivo que se está procesando.\n\n#### Variables de plantilla interactivo\n\nSi no proporcionas todas las variables en la línea de comandos, se solicitarán interactivamente.\n\nLa struct definida debe incluir las variables en una seccion de `variables` con la siguiente estructura:\n\n```yaml\nvariables:\n  - variable_name:\n      description: \"Descripción de la variable\"\n      type: string\n      default: \"Valor predeterminado\"\n```\n\ncomo 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.\n\n#### Filtros personalizados de Jinja2\n\n##### `latest_release`\n\nEste filtro obtiene la versión más reciente de una release en un repositorio de GitHub. Toma el nombre del repositorio como argumento.\n\n```yaml\nstructure:\n  - README.md:\n      content: |\n        # MyProject\n        Latest release: {{@ \"httpdss/struct\" | latest_release @}}\n```\n\nEsto 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.\n\nSi ocurre un error en el proceso, el filtro devolverá `LATEST_RELEASE_ERROR`.\n\nNOTA: 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 @}}`.\n\n##### `slugify`\n\nEste filtro convierte una cadena en un slug. Toma un argumento opcional para especificar el carácter separador (el valor predeterminado es `-`).\n\n```yaml\nstructure:\n  - README.md:\n      content: |\n        # {{@ project_name @}}\n        This is a template repository.\n        slugify project_name: {{@ project_name | slugify @}}\n```\n\n##### `default_branch`\n\nEste filtro obtiene el nombre de la rama predeterminada de un repositorio de GitHub. Toma el nombre del repositorio como argumento.\n\n```yaml\nstructure:\n  - README.md:\n      content: |\n        # MyProject\n        Default branch: {{@ \"httpdss/struct\" | default_branch @}}\n```\n\n### Cláusula `with`\n\nLa 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.\n\nEjemplo:\n\n```yaml\nfolders:\n  - .devops/modules/mod1:\n      struct: terraform/module\n  - .devops/modules/mod2:\n      struct: terraform/module\n      with:\n        module_name: mymod2\n```\n\n## 📝 Esquema YAML\n\nPara 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.\n\n### Configuración en VSCode\n\n1. Instala la [extensión YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) para VSCode.\n2. Añade la siguiente configuración a los ajustes de tu espacio de trabajo (`.vscode/settings.json`):\n\n```json\n{\n  \"yaml.schemas\": {\n    \"https://raw.githubusercontent.com/httpdss/struct/refs/heads/main/struct-schema.json\": \".struct.yaml\"\n  }\n}\n```\n\nEsta configuración asociará el esquema JSON con todos los archivos .struct.yaml en tu espacio de trabajo, proporcionando validación y autocompletado.\n\n## 🔄 Script de Disparador de GitHub\n\nEl 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.\n\n### 📋 Características\n\n- Filtra repositorios por un tema específico (por ejemplo, `struct-enabled`).\n- Verifica la existencia de un archivo `.struct.yaml` en la rama predeterminada del repositorio.\n- Comprueba la presencia del archivo de flujo de trabajo `run-struct` en `.github/workflows/`.\n- Activa el evento de despacho del flujo de trabajo en los repositorios elegibles.\n\n### 🚀 Uso\n\nPara usar el script, asegúrate de cumplir con los siguientes requisitos:\n\n1. Un token de acceso personal de GitHub válido con los permisos necesarios (configurado como la variable de entorno `GITHUB_TOKEN`).\n2. La biblioteca `PyGithub` instalada (`pip install PyGithub`).\n\nEjecuta el script con el siguiente comando:\n\n```sh\npython3 scripts/github-trigger.py \u003corganización\u003e \u003ctema\u003e\n```\n\n#### Argumentos\n\n- `\u003corganización\u003e`: El nombre de la organización de GitHub.\n- `\u003ctema\u003e`: El tema para filtrar los repositorios (por ejemplo, `struct-enabled`).\n\n#### Ejemplo\n\n```sh\nexport GITHUB_TOKEN=tu_token_de_acceso_personal\npython3 scripts/github-trigger.py mi-org struct-enabled\n```\n\n### 🛠️ Cómo Funciona\n\n1. El script se conecta a la API de GitHub utilizando el token proporcionado.\n2. Itera a través de todos los repositorios privados de la organización especificada.\n3. Para cada repositorio:\n   - Verifica si el repositorio tiene el tema especificado.\n   - Comprueba la existencia de un archivo `.struct.yaml` en la rama predeterminada.\n   - Confirma la presencia del archivo de flujo de trabajo `run-struct`.\n   - Activa el evento de despacho del flujo de trabajo si se cumplen todas las condiciones.\n\n### ⚠️ Notas\n\n- Asegúrate de configurar la variable de entorno `GITHUB_TOKEN` antes de ejecutar el script.\n- El token debe tener permisos suficientes para acceder a repositorios privados y activar flujos de trabajo.\n- Los errores durante la ejecución (por ejemplo, archivos faltantes o permisos insuficientes) se registrarán en la consola.\n\n## 👩‍💻 Desarrollo\n\nPara comenzar con el desarrollo, sigue estos pasos:\n\n- Clona el repositorio\n- Crea un entorno virtual\n\n```sh\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n- Instala las dependencias\n\n```sh\npip install -r requirements.txt\npip install -r requirements.dev.txt\n```\n\n## 📜 Licencia\n\nEste proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.\n\n## 💰 Financiamiento\n\nSi encuentras este proyecto útil, considera apoyarlo a través de donaciones: [patreon/structproject](https://patreon.com/structproject)\n\n## 🤝 Contribuyendo\n\n¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request.\n\n## 🙏 Agradecimientos\n\nUn agradecimiento especial a todos los contribuyentes que hicieron posible este proyecto.\n\n## 🐞 Problemas Conocidos\n\n- [ ] TBD\n","funding_links":["https://patreon.com/structproject","https://www.paypal.me/httpdss"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttpdss%2Fstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhttpdss%2Fstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttpdss%2Fstruct/lists"}