Add automation around generating CLI and config

.github/actions/bootstrap/action.yaml

@@ -20,17 +20,35 @@ inputs:
   bootstrap-apt-packages:
     description: "Space delimited list of tools to install via apt"
     default: ""
+  python-version:
+    description: "Python version to install"
+    required: false
+    default: "3.11"
+  uv-version:
+    description: "UV version to install"
+    required: true
+    default: "0.5.16"
 
 runs:
   using: "composite"
   steps:
     - name: Setup node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
       if: inputs.node-version != ''
       with:
         node-version: ${{ inputs.node-version }}
         cache: 'npm'
 
+    - uses: astral-sh/setup-uv@d9e0f98d3fc6adb07d1e3d37f3043649ddad06a1 # v6.5.0
+      if: inputs.python-version != ''
+      with:
+        enable-cache: true
+
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      if: inputs.python-version != ''
+      with:
+        python-version: ${{ inputs.python-version }}
+
     - name: Restore tool cache
       if: inputs.tools == 'true'
       id: tool-cache
@@ -45,15 +63,10 @@ runs:
       run: make tools
 
     - name: Install dependencies
-      if: inputs.dependencies == 'true' && inputs.node-version != ''
+      if: inputs.dependencies == 'true'
       shell: bash
       run: make install
 
-    - name: Install CI dependencies
-      if: inputs.dependencies == 'true' && inputs.node-version != ''
-      shell: bash
-      run: npm ci
-
     - name: Install apt packages
       if: inputs.bootstrap-apt-packages != ''
       shell: bash
@@ -62,3 +75,10 @@ runs:
       run: |
         IFS=' ' read -ra packages <<< "$APT_PACKAGES"
         DEBIAN_FRONTEND=noninteractive sudo apt update && sudo -E apt install -y "${packages[@]}"
+
+    - name: Restore ecosystem tool cache
+      if: inputs.tools == 'true'
+      uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+      with:
+        path: ${{ github.workspace }}/.cache
+        key: ${{ inputs.cache-key-prefix }}-${{ runner.os }}-ecosystem-tool

.github/dependabot.yml

@@ -18,4 +18,4 @@ updates:
     open-pull-requests-limit: 5
     commit-message:
       prefix: "actions"
-      include: "scope"
+      include: "scope"

.github/workflows/update-reference-docs.yaml

@@ -0,0 +1,95 @@
+name: Update Reference Documentation
+
+on:
+#  schedule:
+#    # Run daily at 2 AM UTC
+#    - cron: '0 2 * * *'
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'scripts/generate_reference_*'
+      - 'tasks.d/generate.yaml'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-docs:
+    name: Update Reference Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          submodules: true
+          persist-credentials: false
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Bootstrap environment
+        uses: ./.github/actions/bootstrap
+
+      - name: Generate reference documentation
+        run: |
+          echo "Generating reference documentation..."
+          .tool/task generate:reference
+
+      - name: Check for changes
+        id: check-changes
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+          if git diff --quiet content/docs/reference/commands/; then
+            echo "No changes detected"
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "Changes detected in reference documentation"
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+
+            # Show what changed
+            echo "Changed files:"
+            git diff --name-only content/docs/reference/commands/
+
+            # Show diff stats
+            echo "Diff summary:"
+            git diff --stat content/docs/reference/commands/
+          fi
+
+      - uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a #v2.1.0
+        id: generate-token
+        with:
+          app_id: ${{ secrets.TOKEN_APP_ID }}
+          private_key: ${{ secrets.TOKEN_APP_PRIVATE_KEY }}
+
+      - name: Create Pull Request
+        if: steps.check-changes.outputs.has-changes == 'true'
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e  # v7.0.8
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          signoff: true
+          commit-message: |
+            Update cli/config reference documentation (auto generated)
+          title: "📚 Update cli/config reference documentation"
+          body: |
+            ## 🤖 Automated Reference Documentation Update
+
+            This PR contains automatic updates to the reference documentation generated from the latest container images.
+
+            ### Changes Include:
+            - Updated CLI command documentation
+            - Updated configuration documentation
+            - Latest version information and help text
+
+            ⚡ This PR was automatically generated by the `update-reference-docs` workflow.
+          branch: update-reference-docs-${{ github.run_number }}
+          branch-suffix: timestamp
+          labels: |
+            documentation
+            automated
+            reference
+          draft: false
+          delete-branch: true

.github/workflows/validations.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Restore link check cache
         uses: actions/cache@v4
         with:
-          path: .lycheecache
+          path: .cache/lychee
           key: cache-lychee
 
       - name: Run validations

.github/zizmor.yml

@@ -1 +1 @@
-rules:
+rules:

.gitignore

@@ -8,12 +8,17 @@ CLAUDE.md
 .task
 .tool
 tmp/
+TODO.md
 
-# testing
-.lycheecache
+# cache directories
+.cache/
 
 # python
+/venv
 .venv/
+**/__pycache__/
+*.pyc
+.coverage
 
 # javascript
 node_modules/

.lychee.toml

@@ -1,5 +1,5 @@
 # note: run with
-#  lychee -c lychee.toml --root-dir "$(pwd)/public"  ./public
+#  lychee -c .lychee.toml --root-dir "$(pwd)/public"  ./public
 
 # this only caches external URLs
 cache = true

.markdownlint-cli2.jsonc

@@ -4,4 +4,4 @@
     // TODO(alex): the generator needs some work, in the meantime we'll ignore the generated files
     "content/docs/releases/**/*.md"
   ]
-}
+}

.markdownlint.jsonc

@@ -31,4 +31,4 @@
   "MD050": {
     "style": "asterisk"
   }
-}
+}

.pre-commit-config.yaml

@@ -0,0 +1,93 @@
+# the default is to run these on commit + push
+default_stages:
+  - pre-push
+
+repos:
+  # Universal repository concerns (not stack-specific)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.4.0
+    hooks:
+      # prevent giant files from being committed
+      - id: check-added-large-files
+        stages:
+          - pre-push
+
+      # checks for a common error of placing code before the docstring
+      - id: check-docstring-first
+        stages:
+          - pre-push
+
+      # attempts to load all yaml files to verify syntax
+      - id: check-yaml
+        stages:
+          - pre-push
+
+      # attempts to load all json files to verify syntax
+      - id: check-json
+        stages:
+          - pre-push
+
+      # makes sure files end in a newline and only a newline
+      - id: end-of-file-fixer
+        exclude: '^tests/(fixtures|snapshots)/'
+        stages:
+          - pre-push
+
+      # trims trailing whitespace
+      - id: trailing-whitespace
+        stages:
+          - pre-push
+
+      # check for files that contain merge conflict strings
+      - id: check-merge-conflict
+        stages:
+          - pre-push
+
+      # simply check whether files parse as valid python
+      - id: check-ast
+        stages:
+          - pre-push
+
+      # check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT
+      - id: check-case-conflict
+        stages:
+          - pre-push
+
+  #  # GitHub Actions linting
+  #  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+  #    rev: v1.12.1
+  #    hooks:
+  #      - id: zizmor
+
+  # Stack-specific hooks (delegates to task namespaces)
+  - repo: local
+    hooks:
+      # Hugo/Node stack
+      - id: hugo-lint-fix
+        name: hugo-lint-fix
+        entry: make hugo:lint-fix
+        pass_filenames: false
+        language: system
+        files: \.(md|html|yaml|toml|css|js)$
+
+      # Python stack
+      - id: python-lint-fix
+        name: python-lint-fix
+        entry: make python:lint-fix
+        pass_filenames: false
+        language: system
+        files: \.py$
+
+      - id: python-format
+        name: python-format
+        entry: make python:format
+        pass_filenames: false
+        language: system
+        files: \.py$
+
+      - id: python-types
+        name: python-types
+        entry: make python:check-types
+        pass_filenames: false
+        language: system
+        files: \.py$

.prettierignore

@@ -29,4 +29,4 @@ content/docs/releases/*/v*.md
 *.woff
 *.woff2
 *.ttf
-*.eot
+*.eot

Makefile

@@ -37,4 +37,4 @@ $(TASKS): $(TASK)
 	@$(TASK) $@
 
 help: $(TASK)
-	@$(TASK) -l
+	@$(TASK) -l