diff --git a/.continue/.markdownlint.json b/.continue/.markdownlint.json new file mode 100644 index 0000000..3eb7f83 --- /dev/null +++ b/.continue/.markdownlint.json @@ -0,0 +1,3 @@ +{ + "MD041": false +} diff --git a/.continue/rules/ansible.md b/.continue/rules/ansible.md new file mode 100644 index 0000000..4833106 --- /dev/null +++ b/.continue/rules/ansible.md @@ -0,0 +1,127 @@ +--- +name: Ansible Best Practices +description: Ansible best practices and conventions +alwaysApply: false +globs: + - "**/*.yml" + - "**/*.yaml" +--- + +You are an expert Ansible automation engineer. + +When working with Ansible content, always follow these rules: + +## General + +- Prefer **idempotent** solutions; tasks must be safe to run multiple times. +- Use **Ansible built-in modules** instead of shell or command whenever possible. +- Do not assume root access; use `become: true` only when required. +- Avoid hard-coded values; prefer variables, defaults, and group/host vars. +- Use clear, descriptive task names. +- Ensure all YAML is valid, properly indented, and ansible-lint compliant. +- Favor clarity and maintainability over cleverness. +- Add README files to complex directories. +- Document complex algorithms and business rules. +- Maintain up-to-date dependencies list. + +## Security Hardening + +- **Never embed secrets** directly in playbooks, roles, or templates. +- Use **Ansible Vault**, external secret managers, or injected variables for secrets. +- Mark sensitive tasks with: + + ```yaml + no_log: true + ``` + +- Avoid leaking secrets via debug, register, or error messages. +- Use least privilege: + - Avoid running entire plays as root. + - Scope become to individual tasks where possible. +- Set secure file permissions explicitly: + + ```yaml + mode: "0640" + owner: root + group: root + ``` + +- Validate downloaded files using checksums. +- Avoid ignore_errors for security-sensitive operations. +- Do not disable SSL/TLS validation unless explicitly required and documented. +- Prefer validate_certs: true for network modules. +- Assume hosts may be compromised—do not trust remote state blindly. + +## Playbooks + +- Use `hosts`, `gather_facts`, and `become` explicitly. +- Keep playbooks minimal; delegate logic to roles. +- Apply tags consistently for safe partial execution. +- Use serial for rolling updates to reduce blast radius. +- Avoid large monolithic plays. + +## Roles + +- Follow the standard role structure: + (`tasks/`, `handlers/`, `defaults/`, `vars/`, `templates/`, `files/`). +- Put overridable values in `defaults/main.yml`. +- Put non-overridable or internal values in `vars/main.yml`. +- Namespace all role variables (role_name_variable). +- Use meta/main.yml to define role dependencies. +- Use handlers only when a change requires a follow-up action. + +## Tasks + +- Always name tasks clearly and descriptively. +- Use `state: present/absent/latest` explicitly. +- Register variables only when they are actually used. +- Use `changed_when` and `failed_when` to ensure correct task status. +- Avoid `ignore_errors` unless absolutely necessary. +- Avoid shell unless absolutely unavoidable; document why if used. +- Prefer creates and removes when using command-like tasks. +- Avoid unnecessary loops; simplify logic where possible. + +## Variables & Templates + +- Use snake_case for variable names. +- Quote variables in YAML to prevent parsing issues. +- Namespace role variables (e.g., `nginx_port`, not `port`). +- Avoid complex logic in templates—use when instead. +- Use Jinja2 filters safely and defensively (default, bool, int). +- Do not reference undefined variables without defaults. + +## Conditionals & Loops + +- Use when for conditionals. +- Prefer `loop` over deprecated `with_*`. +- Use `ansible_facts` instead of shell commands for system data. +- Avoid deeply nested conditionals. + +## Error Handling & Validation + +- Fail fast on critical errors. +- Use assert to validate assumptions. +- Use check_mode compatibility whenever possible. +- Ensure tasks behave correctly in --diff and --check. + +## Linting & Compatibility + +- Code must comply with ansible-lint. +- Write code compatible with recent Ansible versions. +- Avoid deprecated modules and syntax. +- Do not rely on undefined behavior or undocumented features. + +## Performance & Reliability (Tips & Tricks) + +- Use gather_facts: false if facts are not needed. +- Use run_once and delegate_to when appropriate. +- Cache facts when operating at scale. +- Avoid repeated expensive operations. +- Prefer block for grouping related tasks and error handling. + +## Output Expectations + +- Generated YAML must be valid and properly indented. +- Provide minimal but sufficient comments when clarity is needed. +- Do not include explanations unless explicitly requested. +- Assume production usage and security-sensitive environments. diff --git a/.continue/rules/repo-readme.md b/.continue/rules/repo-readme.md new file mode 100644 index 0000000..139f3ac --- /dev/null +++ b/.continue/rules/repo-readme.md @@ -0,0 +1,159 @@ +--- +name: Project README Standards +globs: "**/README.md" +alwaysApply: false +description: Guidelines for creating comprehensive project README files +tags: + - readme + - documentation + - markdown + - project-setup + - best-practices +--- + +You are an expert in: + +- technical documentation +- open source best practices +- developer experience. + +## README Structure + +A well-structured README should include these sections in order: + +1. Project Title and Description +2. Badges (build status, version, license) +3. Key Features +4. Screenshots/Demo (if applicable) +5. Quick Start +6. Installation +7. Usage Examples +8. API Reference (or link to docs) +9. Configuration +10. Contributing +11. License + +## Essential Sections + +### Project Header + +```markdown +# Project Name + +> One-line description of what this project does + +[![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](https://github.com/user/repo/actions) +[![npm version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name) +[![License](https://img.shields.io/github/license/user/repo)](LICENSE) + +Brief paragraph explaining the project's purpose, main features, +and why someone would want to use it. +``` + +### Quick Start + +```markdown +## Quick Start + +Get up and running in less than 5 minutes: + +\`\`\`bash +npm install package-name +npm run dev +\`\`\` + +Visit http://localhost:3000 to see the application. +``` + +### Installation + +```markdown +## Installation + +### Prerequisites + +- Node.js 18+ +- PostgreSQL 14+ +- Redis 6.2+ + +### Install from npm + +\`\`\`bash +npm install package-name +\`\`\` + +### Install from source + +\`\`\`bash +git clone https://github.com/user/repo.git +cd repo +npm install +npm run build +\`\`\` +``` + +### Usage Examples + +```markdown +## Usage + +### Basic Example + +\`\`\`javascript +import { Widget } from 'package-name'; + +const widget = new Widget({ +apiKey: 'your-api-key', +theme: 'dark' +}); + +widget.render('#app'); +\`\`\` + +### Advanced Example + +\`\`\`javascript +// Custom configuration with error handling +const widget = new Widget({ +apiKey: process.env.API_KEY, +theme: 'dark', +onError: (error) => { +console.error('Widget error:', error); +} +}); + +// Add custom event handlers +widget.on('ready', () => { +console.log('Widget is ready'); +}); + +widget.render('#app'); +\`\`\` +``` + +## Best Practices + +- Keep the README focused and concise +- Use clear, simple language +- Include code examples that actually work +- Add visuals when they help understanding +- Link to more detailed documentation +- Keep examples up-to-date with the code +- Test your installation instructions regularly + +## Common Mistakes to Avoid + +- Don't assume reader knowledge +- Don't skip the Quick Start section +- Don't use jargon without explanation +- Don't forget to update version numbers +- Don't include sensitive information + +## Formatting Tips + +- Use consistent heading levels +- Include a table of contents for long READMEs +- Use code blocks with language highlighting +- Add alt text to images +- Use tables for comparing options +- Include emoji sparingly and purposefully diff --git a/.gitea/workflows/AiReviewPR.yaml b/.gitea/workflows/AiReviewPR.yaml new file mode 100644 index 0000000..d749edb --- /dev/null +++ b/.gitea/workflows/AiReviewPR.yaml @@ -0,0 +1,37 @@ +--- +# https://github.com/kekxv/AiReviewPR +name: ai-reviews + +on: + pull_request: + types: [opened, synchronize] + +jobs: + review: + name: Review PR + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v6 + with: + # Number of commits to fetch. 0 indicates all history for all + # branches and tags. + # Default: 1 + fetch-depth: 0 + # The base URL for the GitHub instance that you are trying to clone + # from, will use environment defaults to fetch from the same instance + # that the workflow is running from unless specified. + # Example URLs are https://github.com or + # https://my-ghes-server.example.com + github-server-url: ${{ vars.GIT_SERVER_URL }} + + - name: Review code + uses: kekxv/AiReviewPR@v0.1.0 + with: + model: ${{ vars.OLLAMA_MODEL }} + host: http://192.168.2.233:11435 + # host: ${{ vars.OLLAMA_HOST }} + # ai_token: ${{ secrets.AI_TOKEN }} + REVIEW_PULL_REQUEST: false + LANGUAGE: English diff --git a/.gitea/workflows/ansible-lint.yml b/.gitea/workflows/ansible-lint.yml index d089d74..f1fd650 100644 --- a/.gitea/workflows/ansible-lint.yml +++ b/.gitea/workflows/ansible-lint.yml @@ -1,15 +1,17 @@ -# .github/workflows/ansible-lint.yml +--- +# .gitea/workflows/ansible-lint.yml name: ansible-lint on: [pull_request, issues, push] jobs: build: - name: Ansible Lint # Naming the build is important to use it as a status check + name: Ansible Lint + # Naming the build is important to use it as a status check runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@v6 with: github-server-url: ${{ vars.GIT_SERVER_URL }} @@ -21,7 +23,11 @@ jobs: - name: Install ansible-lint run: | python -m pip install --upgrade pip - pip install ansible ansible-lint + pip install ansible ansible-lint yamllint + + - name: Run yamllint + run: | + yamllint . - name: Run ansible-lint run: | diff --git a/.gitea/workflows/gitleaks.yml b/.gitea/workflows/gitleaks.yml new file mode 100644 index 0000000..56f1ac1 --- /dev/null +++ b/.gitea/workflows/gitleaks.yml @@ -0,0 +1,35 @@ +--- +name: Gitleaks Scan + +on: + push: + pull_request: + +jobs: + gitleaks: + runs-on: ubuntu-latest + + steps: + - name: Install Gitleaks + run: | + curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.30.0/gitleaks_8.30.0_linux_x64.tar.gz \ + | tar -xz + sudo mv gitleaks /usr/local/bin/ + + - name: Checkout code + uses: actions/checkout@v6 + with: + github-server-url: ${{ vars.GIT_SERVER_URL }} + + - name: Run Gitleaks + run: | + gitleaks dir . \ + --redact=10 \ + --verbose \ + --exit-code 1 + # gitleaks detect \ + # --source . \ + # --no-git \ + # --redact=20 \ + # --verbose \ + # --exit-code 1 diff --git a/.gitea/workflows/markdown-lint.yml b/.gitea/workflows/markdown-lint.yml new file mode 100644 index 0000000..f5b7d15 --- /dev/null +++ b/.gitea/workflows/markdown-lint.yml @@ -0,0 +1,71 @@ +--- +# .gitea/workflows/markdown-lint.yml +name: Markdown Lint + +on: [pull_request, issues, push] + +jobs: + build: + name: markdown-lint + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v6 + with: + github-server-url: ${{ vars.GIT_SERVER_URL }} + + - name: Install Node.js & markdownlint + run: | + apt-get update && apt-get install -y npm + npm install -g markdownlint-cli2 + + - name: Run lint + run: markdownlint-cli2 "**/*.md" "#node_modules" + +# on: +# push: +# branches: +# - main +# pull_request: +# branches: +# - main + +# jobs: +# markdown-lint: +# runs-on: docker +# container: +# image: node:20-alpine +# steps: +# - name: Install dependencies +# run: | +# apk add --no-cache git +# npm install -g markdownlint-cli2 + +# - name: Run Markdown lint +# run: | +# markdownlint-cli2 "**/*.md" "#node_modules" + +#########################################à + +# --- +# https://github.com/marketplace/actions/markdownlint-cli2-action +# name: Markdown Lint + +# on: [pull_request, push] + +# jobs: +# build: +# name: markdown-lint +# runs-on: ubuntu-latest +# steps: +# - name: Checkout code +# uses: actions/checkout@v4 +# with: +# github-server-url: ${{ vars.GIT_SERVER_URL }} + +# - name: Markdown lint +# uses: DavidAnson/markdownlint-cli2-action@v22 +# with: +# globs: '**/*.md' +# fix: true +# continue-on-error: true diff --git a/.gitea/workflows/stale.yml b/.gitea/workflows/stale.yml new file mode 100644 index 0000000..3007d7a --- /dev/null +++ b/.gitea/workflows/stale.yml @@ -0,0 +1,72 @@ +--- +# This workflow warns and then closes issues and PRs that have +# had no activity for a specified amount of time. +# +# You can adjust the behavior by modifying this file. +# For more information, see: +# https://github.com/actions/stale +name: Mark stale issues and pull requests + +on: + schedule: + - cron: '21 3 * * *' + +jobs: + stale: + + runs-on: ubuntu-latest + permissions: + issues: write # for actions/stale to close stale issues + pull-requests: write # for actions/stale to close stale PRs + + steps: + # - name: Checkout code + # uses: actions/checkout@v4 + # with: + # # Number of commits to fetch. 0 indicates all history for all branches + # # and tags. + # # Default: 1 + # fetch-depth: 0 + # # The base URL for the GitHub instance that you are trying to clone from, + # # will use environment defaults to fetch from the same instance that the + # # workflow is running from unless specified. + # # Example URLs are https://github.com or + # # https://my-ghes-server.example.com + # github-server-url: ${{ vars.GIT_SERVER_URL }} + + # The 90 day stale policy + # Used for: + # - Issues & PRs + # - No PRs marked as no-stale or pinned + # - No issues marked as no-stale, help-wanted or pinned + - name: 90 days stale issues & PRs policy + uses: actions/stale@v9.1.0 + with: + # repo-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} + token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} + days-before-stale: 90 + days-before-close: 7 + operations-per-run: 150 + remove-stale-when-updated: true + stale-issue-label: "stale" + exempt-issue-labels: "no-stale,help-wanted,pinned,enhancement" + stale-issue-message: > + There hasn't been any activity on this issue recently. To keep our + backlog manageable we have to clean old issues, as many of them have + already been resolved with the latest updates. + + Please make sure to update to the latest version and check if that + solves the issue. Let us know if that works for you by adding a + comment 👍 + + This issue has now been marked as stale and will be closed if no + further activity occurs. Thank you for your contributions. + + stale-pr-label: "stale" + exempt-pr-labels: "no-stale,pinned" + stale-pr-message: > + There hasn't been any activity on this pull request recently. This + pull request has been automatically marked as stale because of that + and will be closed if no further activity occurs within 7 days. + + Thank you for your contributions. diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 0000000..587e4e3 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,2 @@ +# ignore files completely +.continue/rules/**/*.md diff --git a/.yamllint b/.yamllint new file mode 100644 index 0000000..4e2c44a --- /dev/null +++ b/.yamllint @@ -0,0 +1,23 @@ +--- +# This is my first, very own configuration file for yamllint! +# It extends the default conf by adjusting some options. + +extends: default + +rules: + comments-indentation: disable # don't bother me with this rule + truthy: + allowed-values: ['true', 'false', 'yes', 'no', 'on'] + comments: + min-spaces-from-content: 1 + + braces: + max-spaces-inside: 1 + + octal-values: + forbid-implicit-octal: true + forbid-explicit-octal: true + + line-length: + max: 120 + allow-non-breakable-words: true