From 28d493934adbb13a084fb36535293d2a63101617 Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Sun, 29 Jun 2025 15:38:27 +0000 Subject: [PATCH] Add detailed instructions for generating `.struct.yaml` files and update structure definitions --- .github/instructions/struct.instructions.md | 94 ++++++++++++++++ docs/structures.md | 119 ++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 .github/instructions/struct.instructions.md diff --git a/.github/instructions/struct.instructions.md b/.github/instructions/struct.instructions.md new file mode 100644 index 0000000..75ce17b --- /dev/null +++ b/.github/instructions/struct.instructions.md @@ -0,0 +1,94 @@ +--- +applyTo: '**' +--- + +# Struct Assistant + +## Role + +You are an expert assistant that generates valid `.struct.yaml` files for the [STRUCT tool](https://github.com/httpdss/struct), which automates project structure generation from YAML configuration. + +## Defining the `.struct.yaml` file + +this file has 3 main keys: `structures`, `folders`, and `variables`. + +### Defining file structures + +The `files` key is used to define files that are created. Each file path should have a reference to the content it needs to put on the file or the content of the file itself. +For referencing the content of a file, you can use the `file:` key with the path to the file. this can also be a remote https file. +The content of the file can be defined using the `content:` key with a pipe notation (`|`) for multiline content. + +```yaml +files: + - path/to/file.txt: + content: | + This is the content of the file. + - path/to/remote/file.txt: + file: https://example.com/file.txt +``` + +### Defining folders + +The `folders` key is used to define folders that are created. Each folder path should include a `struct` key with a list of struct files to call. Optionally, you can define the value of a variable using the `with:` key. +The list of struct files available can be taken from all the files defined inside `struct_module/contribs/`. +Remember the name of the struct file is the path to the file without the `.yaml` extension. +Read from the struct file to kown the variables that can be used. + +```yaml +folders: + - ./path/to/folder/: + struct: + - terraform/module + with: + variable_name: value + - ./: + struct: + - github/prompts/struct +``` + +### Defining variables + +The `variables` key is used to define variables that can be used in the struct files. Each variable should have a description, type, and optional default value. + +```yaml +variables: + - variable_name: + description: Description of the variable + type: string + default: default_value +``` + +## Important notes + +- Follow the JSON Schema definition provided in the references. +- Use valid keys: `files`, `folders`, and `variables`. +- if you want to define files, use the `files:` key, and a list of file paths that are created. each file path should have a content key. +- if you want to define folders, use the `folders:` key, and a list of folder paths that are created. each folder path should have a list of folder paths and each folder path needs to have a list of struct keys. also if you want to define the value of a variable then you should use the `with:` key. +- Follow the conventions from the STRUCT README provided in the references. +- Include content blocks under `content:` using pipe notation (`|`) when needed. +- Use `permissions`, `skip`, or `skip_if_exists` if specified. This is used only for the `files` key. +- Use `file:` to reference the content of a file or `content:` to define the content of the file. +- Use `struct:` to define the list of struct files to call for a folder. +- When defining the list of struct files you want to use, make sure to query the `structure name` to know what to use. this will be at ../../docs/structures.md. +- Optionally, use Jinja2 custom filters such as `| latest_release`, `| default_branch`, or `| slugify`. +- before creating a file from scratch, check that there is no struct contrib available that can be used to create the file. + +## Output + +Only output the YAML content, no explanation or prose. + +## Example usage + +- Create a project template for a Python CLI tool +- Generate a Terraform module with `terraform/module` sub-struct +- Using interactive variables for author/project name + +If unsure of a value, use sensible defaults or define a variable. + +Always return YAML that is syntactically correct and validated against the provided schema. + +## References + +- [STRUCT json schema](../../struct-schema.json) +- [STRUCT README](../../README.md) +- [Structures available in contribs](../../doc/structures.md) diff --git a/docs/structures.md b/docs/structures.md index 0ef9499..9580159 100644 --- a/docs/structures.md +++ b/docs/structures.md @@ -1,129 +1,248 @@ # List of Structures in `struct_module/contribs` ## Ansible Playbook + - **File**: `ansible-playbook.yaml` - **Description**: Contains the structure for an Ansible playbook with various components like `main.yml`, `vars.yml`, `tasks/main.yml`, `handlers/main.yml`, `templates/README.md`, and `README.md`. +- **Structure name**: `ansible_playbook` ## CI/CD Pipelines + - **File**: `ci-cd-pipelines.yaml` - **Description**: Defines the structure for CI/CD pipelines including `.gitlab-ci.yml`, `Jenkinsfile`, `.github/workflows/ci.yml`, and `.github/workflows/cd.yml`. +- **Structure name**: `ci_cd_pipelines` ## CloudFormation Files + - **File**: `cloudformation-files.yaml` - **Description**: Contains the structure for AWS CloudFormation files including `template.yaml`, `parameters.json`, and `deploy.sh`. +- **Structure name**: `cloudformation_files` ## Codeowners Configuration + - **File**: `configs/codeowners.yaml` - **Description**: Defines the structure for a `CODEOWNERS` file. +- **Structure name**: `configs/codeowners` ## Devcontainer Configuration + - **File**: `configs/devcontainer.yaml` - **Description**: Contains the structure for a `.devcontainer/devcontainer.json` file. +- **Structure name**: `configs/devcontainer` ## Editor Config + - **File**: `configs/editor-config.yaml` - **Description**: Defines the structure for an `.editorconfig` file. +- **Structure name**: `configs/editor-config` ## ESLint Configuration + - **File**: `configs/eslint.yaml` - **Description**: Contains the structure for ESLint configuration files including `.eslintrc.json` and `.eslintignore`. +- **Structure name**: `configs/eslint` ## JSHint Configuration + - **File**: `configs/jshint.yaml` - **Description**: Defines the structure for JSHint configuration files including `.jshintrc` and `.jshintignore`. +- **Structure name**: `configs/jshint` + +## Kubectl Configuration + +- **File**: `configs/kubectl.yaml` +- **Description**: Contains the structure for a `.kuberc` configuration file. +- **Structure name**: `configs/kubectl` ## Prettier Configuration + - **File**: `configs/prettier.yaml` - **Description**: Contains the structure for Prettier configuration files including `.prettierrc` and `.prettierignore`. +- **Structure name**: `configs/prettier` ## Docker Files + - **File**: `docker-files.yaml` - **Description**: Defines the structure for Docker-related files including `Dockerfile`, `.dockerignore`, `docker-compose.yml`, and `.env`. +- **Structure name**: `docker-files` ## Documentation Template + - **File**: `documentation-template.yaml` - **Description**: Contains the structure for documentation files including `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `LICENSE.md`. +- **Structure name**: `documentation-template` ## Git Hooks + - **File**: `git-hooks.yaml` + - **Description**: Defines the structure for Git hook scripts including `.git/hooks/pre-commit`, `.git/hooks/pre-push`, and `.git/hooks/commit-msg`. +- **Structure name**: `git-hooks` ## GitHub Workflows + - **File**: `github/workflows/execute-tf-workflow.yaml` - **Description**: Contains the structure for a GitHub Actions workflow to execute Terraform. +- **Structure name**: `github/workflows/execute-terraform-workflow` + +## Github Labeler Workflow + +- **File**: `github/workflows/labeler.yaml` +- **Description**: Defines the structure for a GitHub Actions workflow to label issues and pull requests. +- **Structure name**: `github/workflows/labeler` + +## GitHub stale Workflow + +- **File**: `github/workflows/stale.yaml` +- **Description**: Contains the structure for a GitHub Actions workflow to mark stale issues and pull requests. +- **Structure name**: `github/workflows/stale` ## GitHub Pre-commit Workflow + - **File**: `github/workflows/pre-commit.yaml` - **Description**: Defines the structure for a GitHub Actions workflow to run pre-commit hooks. +- **Structure name**: `github/workflows/pre-commit` ## GitHub Release Drafter Workflow + - **File**: `github/workflows/release-drafter.yaml` - **Description**: Contains the structure for a GitHub Actions workflow to draft releases. +- **Structure name**: `github/workflows/release-drafter` ## GitHub Run Struct Workflow + - **File**: `github/workflows/run-struct.yaml` - **Description**: Defines the structure for a GitHub Actions workflow to run Struct. +- **Structure name**: `github/workflows/run-struct` + +## GitHub Templates + +- **File**: `github/templates.yaml` +- **Description**: Contains the structure for GitHub templates including `ISSUE_TEMPLATE/bug_report.yaml`, `ISSUE_TEMPLATE/feature_request.yaml`, and `PULL_REQUEST_TEMPLATE.md`. +- **Structure name**: `github/templates` ## Helm Chart + - **File**: `helm-chart.yaml` - **Description**: Contains the structure for a Helm chart including `Chart.yaml`, `values.yaml`, and various templates. +- **Structure name**: `helm-chart` + +## Github Instructions + +- **File**: `github/instructions/generic.yaml` +- **Description**: Defines the structure for generic GitHub instructions. `generic.instruction.md` +- **Structure name**: `github/instructions/generic` + +## Github generic prompt + +- **File**: `github/prompt/generic.yaml` +- **Description**: Contains the structure for a generic GitHub prompt. +- **Structure name**: `github/prompt/generic` + +## Github react form prompt + +- **File**: `github/prompt/react-form.yaml` +- **Description**: Defines the structure for a React form prompt in GitHub. +- **Structure name**: `github/prompt/react-form` + +## Github security api prompt + +- **File**: `github/prompt/security-api.yaml` +- **Description**: Contains the structure for a GitHub security API prompt. +- **Structure name**: `github/prompt/security-api` + +## Github struct prompt + +- **File**: `github/prompt/struct.yaml` +- **Description**: Defines the structure for a Struct prompt in GitHub. +- **Structure name**: `github/prompt/struct` ## Kubernetes Manifests + - **File**: `kubernetes-manifests.yaml` - **Description**: Defines the structure for Kubernetes manifests including `deployment.yaml`, `service.yaml`, `ingress.yaml`, `configmap.yaml`, `secrets.yaml`, and `README.md`. +- **Structure name**: `kubernetes-manifests` ## Generic Project + - **File**: `project/generic.yaml` - **Description**: Contains the structure for a generic project with various configuration files and folders. +- **Structure name**: `project/generic` ## Go Project + - **File**: `project/go.yaml` - **Description**: Defines the structure for a Go project including `.editorconfig`, `.env`, `.gitignore`, `LICENSE`, `README.md`, `main.go`, and various folders. +- **Structure name**: `project/go` ## Java Project + - **File**: `project/java.yaml` - **Description**: Contains the structure for a Java project including `.editorconfig`, `.env`, `.gitignore`, `LICENSE`, `README.md`, `pom.xml`, and various folders. +- **Structure name**: `project/java` ## Node.js Project + - **File**: `project/nodejs.yaml` - **Description**: Defines the structure for a Node.js project. +- **Structure name**: `project/nodejs` ## Python Project + - **File**: `project/python.yaml` - **Description**: Contains the structure for a Python project. +- **Structure name**: `project/python` ## Ruby Project + - **File**: `project/ruby.yaml` - **Description**: Defines the structure for a Ruby project. +- **Structure name**: `project/ruby` ## Rust Project + - **File**: `project/rust.yaml` - **Description**: Contains the structure for a Rust project. +- **Structure name**: `project/rust` ## AWS Accounts Terraform + - **File**: `terraform/apps/aws-accounts.yaml` - **Description**: Defines the structure for AWS accounts Terraform configuration. +- **Structure name**: `terraform/apps/aws-accounts` ## Environments Terraform + - **File**: `terraform/apps/environments.yaml` - **Description**: Contains the structure for environments Terraform configuration. +- **Structure name**: `terraform/apps/environments` ## Generic Terraform + - **File**: `terraform/apps/generic.yaml` - **Description**: Defines the structure for generic Terraform configuration. +- **Structure name**: `terraform/apps/generic` ## GitHub Organization Terraform + - **File**: `terraform/apps/github-organization.yaml` - **Description**: Contains the structure for GitHub organization Terraform configuration. +- **Structure name**: `terraform/apps/github-organization` ## Init Terraform + - **File**: `terraform/apps/init.yaml` - **Description**: Defines the structure for init Terraform configuration. +- **Structure name**: `terraform/apps/init` ## Generic Terraform Module + - **File**: `terraform/modules/generic.yaml` - **Description**: Contains the structure for a generic Terraform module. +- **Structure name**: `terraform/modules/generic` ## Vagrant Files + - **File**: `vagrant-files.yaml` - **Description**: Defines the structure for Vagrant files. +- **Structure name**: `vagrant-files`