nullforge 0.1.0__tar.gz

nullforge-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

nullforge-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @wlix13

nullforge-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contribution Guidelines
+
+First of all, thank you for your interest in the project.
+
+Regardless of whether you are thinking about creating an issue or opening a pull request, I truly appreciate the help.
+Without communication, I cannot know what the community wants, what they use or how they use it.
+Pull requests and issues are exactly what gives me the visibility I need, so thank you.
+
+## Getting started
+
+While following the exact process is neither mandatory nor enforced, it is recommended to try following it as it may help avoid wasted efforts.
+
+### Creating an issue
+
+Whether you have a **question**, found a **bug**, would like to see a **new feature** added or anything along those lines, creating an issue is
+going to be the first step. The issue templates will help guide you, but simply creating an issue with the reason for the creation
+of said issue is perfectly fine.
+
+Furthermore, if you don't want to fix the problem or implement the feature yourself, that's completely fine.
+Creating an issue alone will give both the maintainers as well as the other members of the community visibility on said issue,
+which is a lot more likely to get the issue resolved than if the problem/request was left untold.
+
+### Solving an issue
+
+Looking to contribute? Awesome! Look through the open issues in the repository, preferably those that are already labelled.
+
+If you found one that interests you, try to make sure nobody's already working on it.
+Adding a comment to the issue asking the maintainer if you can tackle it is a perfectly acceptable way of doing that!
+
+If there's no issue yet for what you want to solve, start by [Creating an issue](#creating-an-issue), specify
+you'd like to take a shot at solving it, and finally, wait for the maintainer to comment on the issue.
+
+You don't _have_ to wait for the maintainer to comment on the issue before starting to work on it if you're sure that there's no other
+similar existing issues, open or closed, but if the maintainer has commented, it means the maintainer has, based on the comment itself,
+acknowledged the issue.
+
+## Development Setup
+
+### Package Management
+
+This project **only** supports the `uv` installation method. Other tools, such as `conda`
+or `pip`, don't provide any guarantees that they will install the correct
+dependency versions. You will almost certainly have _random bugs, error messages,_, and other problems if you don't use `uv`.
+Please _do not report any issues_ if you use non-standard installations, since almost all such issues are invalid.
+
+Furthermore, `uv` is [up to 115x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md)
+than `pip`, which is another _great_ reason to embrace the new industry-standard
+for Python project management.
+
+**Quick & Easy Installation Method:**
+
+There are many convenient ways to install the uv command on your computer. Please check the link below to see all options.
+
+[Installation Guide](https://docs.astral.sh/uv/getting-started/installation/)
+
+Alternatively, if you want a very quick and easy method, you can install it as follows:
+
+```bash
+pip install -U uv
+```
+
+### Pre-commit Hooks (via prek)
+
+This project uses pre-commit hooks to ensure code quality and consistency. Before making any commits, please install and set up prek:
+
+```bash
+# Install prek (if not already installed)
+uv tool install prek
+# or use with uv run (as dev environment already has it covered)
+uv run prek
+
+# Install the pre-commit hooks
+prek install
+```
+
+The pre-commit hooks will automatically run on each commit to check for:
+
+- Code formatting
+- Linting issues
+- Other quality checks
+
+If any hooks fail, please fix the issues before committing. You can manually run all hooks with:
+
+```bash
+prek run --all-files
+```
+
+## Commits
+
+All commits are expected to follow the conventional commits specification.
+
+```text
+<type>[scope]: <description>
+```
+
+It's not a really big deal if you don't, but the commits in your PR might be squashed into a single commit
+with the appropriate format at the reviewer's discretion.
+
+Here's a few examples of good commit messages:
+
+- `feat(api): Add endpoint to retrieve images`
+- `fix(alerting): Remove bad parameter from Slack alerting provider`
+- `test(security): Add tests for basic auth with bcrypt`
+- `docs: Add paragraph on running the application locally`
+
+## Pull requests
+
+The **pull request title** should be a short, meaningful summary of the change as a
+whole, written in the imperative mood. GitHub pre-fills it with your first commit
+message — please replace that with something descriptive. Examples:
+
+- `Add tor rune with bridge support`
+- `Improve CI/CD caching and test matrix`
+- `Fix swap sizing on small hosts`
+
+A good title reads cleanly in the PR list and the project history. The individual
+**commits** inside the PR still follow Conventional Commits (see [Commits](#commits));
+because PRs are merged with a merge/rebase strategy, those commit messages — not the
+title — drive the release changelog, so the title itself does not need a `type:` prefix.
+
+PRs are labelled automatically from the files they touch (e.g. `runes`, `molds`,
+`ci-cd`, `docs`) and from the **Type of change** checklist in the PR template — tick the
+boxes that apply and the matching `feature` / `bug` / `enhancement` / `refactor` /
+`breaking-change` / `security` label is added. Dependabot PRs are labelled `dependencies`.

nullforge-0.1.0/.github/ISSUE_TEMPLATE/BUG-REPORT.yaml

@@ -0,0 +1,49 @@
+name: "Bug report"
+description: "Found something that's not working as expected? Provide detailed information about the issue to help get it resolved."
+labels:
+  - bug
+
+body:
+  - id: description
+    type: textarea
+    validations:
+      required: true
+    attributes:
+      label: "Describe the bug"
+      description: "Tell what went wrong and how it's affecting your work."
+
+  - id: what-you-see
+    type: textarea
+    attributes:
+      label: "What do you see?"
+      description: "Share what's actually happening - error messages, unexpected behavior, or missing functionality. Screenshots are welcome!"
+
+  - id: what-you-expect
+    type: textarea
+    attributes:
+      label: "What do you expect to see?"
+      description: "Describe the intended behavior - what should have happened instead?"
+
+  - id: steps-to-reproduce
+    type: textarea
+    validations:
+      required: false
+    attributes:
+      label: "List the steps that must be taken to reproduce this issue"
+      description: "Provide exact steps to recreate this bug. Include any code snippets, configuration files, or commands used. The easier it is to reproduce, the quicker it can be fixed!"
+      placeholder: |
+        1. Run `nullforge cast -i inventory.py -r dns`
+        2. Inspect the deploy output or the target host state
+        3. Observe unexpected output or error
+
+  - id: version
+    type: input
+    attributes:
+      label: "Version"
+      description: "Which version of NullForge are you using? (check the release tags or pyproject.toml if unsure)"
+
+  - id: additional-information
+    type: textarea
+    attributes:
+      label: "Additional information"
+      description: "Anything else that might help solve this? Environment details, related issues, or workarounds you've tried."

nullforge-0.1.0/.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yaml

@@ -0,0 +1,31 @@
+name: "Feature request"
+description: "Have an idea that could improve this project? Share your suggestion and help shape the future development."
+labels:
+  - feature
+
+body:
+  - id: description
+    type: textarea
+    validations:
+      required: true
+    attributes:
+      label: "Describe the feature request"
+      description: "Describe the feature or improvement you'd like to see. Be as specific as possible about what it should do and how it should work."
+
+  - id: reason
+    type: textarea
+    attributes:
+      label: "Why would this feature be valuable?"
+      description: "Explain the problem this feature would solve or the benefit it would provide. Include use cases or scenarios where this would be helpful."
+
+  - id: usage-duration
+    type: input
+    attributes:
+      label: "How long have you been using this project?"
+      description: "This helps provide context for your request. Feel free to skip if you prefer not to answer."
+
+  - id: additional-information
+    type: textarea
+    attributes:
+      label: "Additional information"
+      description: "Any other details that might be relevant? Similar features in other tools, implementation ideas, or potential challenges to consider."

nullforge-0.1.0/.github/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: false

nullforge-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+<!--
+PR TITLE: write a short, meaningful summary of the change as a whole, in the
+imperative mood - don't leave the auto-filled first-commit message. Examples:
+  * Add tor rune with bridge support
+  * Improve CI/CD caching and test matrix
+  * Fix swap sizing on small hosts
+Individual commits should still follow Conventional Commits (see CONTRIBUTING.md);
+on merge/rebase those commits drive the release changelog.
+-->
+
+## Type of change
+
+<!-- Please check all that apply - this drives the PR's type labels. -->
+
+- [ ] **Bug fix** (fixes an issue in a rune, mold or deploy behaviour)
+- [ ] **Feature** (adds a new rune, mold or CLI capability)
+- [ ] **Enhancement** (improves existing provisioning logic or output)
+- [ ] **Refactor** (restructures code without changing behaviour)
+- [ ] **Breaking change** (changes existing mold schemas, CLI usage, or deploy behaviour)
+- [ ] **Security** (security-related fix or hardening)
+
+## Description
+
+### Why is this change needed?
+
+<!-- Explain the motivation and context for this change -->
+
+### Related Issues
+
+<!-- Link to related issues using "Fixes #123", "Closes #123", or "Relates to #123" -->
+
+## Testing
+
+<!-- Describe how you tested your changes -->
+
+- [ ] Unit tests added or updated (`uv run poe tests`)
+- [ ] Deployed to a real host
+- [ ] No testing required (documentation changes only)
+
+## Checklist
+
+<!-- Ensure all applicable items are completed before requesting review -->
+
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Linter and type checker pass (`uv run poe check`)
+- [ ] Documentation updated (if applicable)

nullforge-0.1.0/.github/dependabot.yml

@@ -0,0 +1,43 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+    groups:
+      python-deps:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+    groups:
+      pre-commit:
+        patterns:
+          - "*"

nullforge-0.1.0/.github/labeler.yaml

@@ -0,0 +1,50 @@
+version: 1
+labels:
+  # --- by PR "Type of change" checklist ---
+  - label: "feature"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Feature\b'
+  - label: "bug"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Bug fix\b'
+  - label: "enhancement"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Enhancement\b'
+  - label: "refactor"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Refactor\b'
+  - label: "breaking-change"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Breaking change\b'
+  - label: "security"
+    body: '(?m)^\s*-\s*\[[xX]\]\s+\**Security\b'
+
+  # --- by changed paths ---
+  - label: "docs"
+    files:
+      - '^README\.md$'
+      - "^docs/"
+  - label: "ci-cd"
+    files:
+      - '^\.github/'
+  - label: "tests"
+    files:
+      - "^tests/"
+  - label: "dependencies"
+    files:
+      - '^uv\.lock$'
+  - label: "molds"
+    files:
+      - "^nullforge/molds/"
+      - "^nullforge/models/"
+  - label: "runes"
+    files:
+      - "^nullforge/runes/"
+  - label: "smithy"
+    files:
+      - "^nullforge/smithy/"
+  - label: "foundry"
+    files:
+      - "^nullforge/foundry/"
+      - "^nullforge/inventories/"
+  - label: "templates"
+    files:
+      - "^nullforge/templates/"
+  - label: "cli"
+    files:
+      - "^nullforge/cli/"

nullforge-0.1.0/.github/labels.yaml

@@ -0,0 +1,89 @@
+# Core Labels
+- name: "bug"
+  description: "Something is not working"
+  color: "d73a4a"
+
+- name: "feature"
+  description: "New feature or request"
+  color: "a2eeef"
+
+- name: "enhancement"
+  description: "Improvement to existing functionality"
+  color: "0e8a16"
+
+- name: "docs"
+  description: "Documentation updates"
+  color: "0075ca"
+
+- name: "breaking-change"
+  description: "Breaking changes"
+  color: "b60205"
+
+- name: "core"
+  description: "Core & Architecture changes"
+  color: "006b75"
+
+- name: "molds"
+  description: "Configuration molds and domain models"
+  color: "1d76db"
+
+- name: "runes"
+  description: "Provisioning runes"
+  color: "fbca04"
+
+- name: "smithy"
+  description: "Cross-distro helpers and shared provisioning logic"
+  color: "bfdadc"
+
+- name: "foundry"
+  description: "Foundry entrypoints and inventories"
+  color: "5319e7"
+
+- name: "templates"
+  description: "Templates updates"
+  color: "c2e0c6"
+
+- name: "security"
+  description: "Security-related changes"
+  color: "ee0701"
+
+- name: "refactor"
+  description: "Code refactoring"
+  color: "cccccc"
+
+- name: "cli"
+  description: "CLI & Commands"
+  color: "f9d0c4"
+
+- name: "tests"
+  description: "Testing"
+  color: "e99695"
+
+- name: "ci-cd"
+  description: "CI/CD and automation"
+  color: "0052cc"
+
+- name: "dependencies"
+  description: "Changes to dependencies"
+  color: "a569bd"
+
+- name: "automated"
+  description: "Automated changes (bots, scheduled workflows)"
+  color: "ededed"
+
+- name: "skip-changelog"
+  description: "Exclude from changelog"
+  color: "d4c5f9"
+
+# PR Labels
+- name: "duplicate"
+  description: "This issue or PR already exists"
+  color: "cfd3d7"
+
+- name: "invalid"
+  description: "This doesn't seem right"
+  color: "e4e669"
+
+- name: "wontfix"
+  description: "This will not be worked on"
+  color: "ffffff"

nullforge-0.1.0/.github/release.yaml

@@ -0,0 +1,49 @@
+changelog:
+  exclude:
+    labels:
+      - duplicate
+      - invalid
+      - wontfix
+      - skip-changelog
+    authors:
+      - dependabot
+      - dependabot[bot]
+      - github-actions[bot]
+      - renovate[bot]
+
+  categories:
+    - title: 💥 Breaking Changes
+      labels:
+        - breaking-change
+    - title: ✨ Features & Enhancements
+      labels:
+        - feature
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+    - title: 🏗️ Core & Architecture
+      labels:
+        - core
+        - refactor
+    - title: ⚙️ CLI & Commands
+      labels:
+        - cli
+    - title: 📝 Templates
+      labels:
+        - templates
+    - title: 🔧 CI
+      labels:
+        - ci-cd
+    - title: 📚 Documentation
+      labels:
+        - docs
+    - title: 📦 Dependencies
+      labels:
+        - dependencies
+    - title: 🧪 Testing
+      labels:
+        - tests
+    - title: 📝 Other
+      labels:
+        - "*"

nullforge-0.1.0/.github/workflows/check-commit-message-pr.yaml

@@ -0,0 +1,93 @@
+name: 🔍 Check commit message in PR
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-commit-message:
+    name: 🔍 Check commit message in PR
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+
+      - name: Check for fixup commits
+        uses: gsactions/commit-message-checker@16fa2d5de096ae0d35626443bcd24f1e756cafee # v2.0.0
+        with:
+          pattern: "^(?!fixup!).*$"
+          flags: "si"
+          excludeDescription: "true"
+          excludeTitle: "false"
+          checkAllCommitMessages: "true"
+          accessToken: ${{ secrets.GITHUB_TOKEN }}
+          error: |
+            Fixup commits are not allowed in pull requests.
+
+            Found commit message starting with "fixup!" which must be squashed before merging.
+
+            To squash fixup commits, use:
+              git rebase -i --autosquash origin/${{ github.event.pull_request.base.ref }}
+
+            Or manually squash the fixup commits with their target commits.
+
+            After squashing, force push the updated branch:
+              git push --force-with-lease origin ${{ github.event.pull_request.head.ref }}
+
+      - name: Check for Cyrillic characters
+        uses: gsactions/commit-message-checker@16fa2d5de096ae0d35626443bcd24f1e756cafee # v2.0.0
+        with:
+          pattern: "^[^А-Яа-яёЁ]*$"
+          flags: "si"
+          excludeDescription: "false"
+          excludeTitle: "false"
+          checkAllCommitMessages: "true"
+          accessToken: ${{ secrets.GITHUB_TOKEN }}
+          error: |
+            The commit message must contain only Latin characters.
+            Ensure there are no Cyrillic characters in the commit title or description.
+
+      - name: Check for conventional commit message
+        uses: gsactions/commit-message-checker@16fa2d5de096ae0d35626443bcd24f1e756cafee # v2.0.0
+        with:
+          pattern: '^((feat|fix|build|chore|ci|docs|refactor|perf|style|test|revert)(\([\w\/-]+\))?!?: [^\n]+(\n\n(BREAKING CHANGE: [^\n]+|.+))?)$'
+          flags: "si"
+          excludeDescription: "true"
+          excludeTitle: "true"
+          checkAllCommitMessages: "true"
+          accessToken: ${{ secrets.GITHUB_TOKEN }}
+          error: |
+            The commit message does not follow the conventional commit format.
+
+            A conventional commit message should be in the format:
+              <type>[optional scope]: <description>
+
+              [optional body]
+
+              [optional BREAKING CHANGE footer]
+
+            Example:
+              feat(api): add new endpoint
+
+            Or for a breaking change:
+              feat!: send an email to the customer
+
+              BREAKING CHANGE: `extends` key in config file is now used for extending other config files
+
+            Allowed types are: feat, fix, build, chore, ci, docs, refactor, perf, style, test, revert.
+            A '!' can be added after the type/scope for breaking changes (e.g., feat!:, feat(api)!:).
+            Alternatively, a 'BREAKING CHANGE:' footer can be used in the commit body.
+
+            Please rebase and amend the commit messages.

nullforge-0.1.0/.github/workflows/ci-code-quality.yaml

@@ -0,0 +1,80 @@
+name: 🔍 Check code quality
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  quality:
+    name: 🔍 Code Quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - run: uv sync --all-groups
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint code
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run ty check
+
+  hooks:
+    name: 🪝 prek hooks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/prek
+          key: prek-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run prek
+        run: uv run --group dev prek run --all-files --show-diff-on-failure
+        env:
+          # skip ruff duplicates here
+          SKIP: ruff-check,ruff-format
+
+  quality-gate:
+    name: ✅ Code quality passed
+    if: always()
+    needs: [quality, hooks]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Fail if any quality job did not pass
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: |
+          echo "::error::one or more code quality jobs failed or were cancelled"
+          exit 1