Merge pull request #327 from opsmill/stable

Backport Stable

Author: BeArchiTek

.github/file-filters.yml

@@ -28,5 +28,6 @@ markdown_all: &markdown_all
   - "**/*.{md,mdx}"
 
 documentation_all:
+  - *ansible_plugins
   - *doc_files
   - *markdown_all

.github/workflows/workflow-changelog-and-docs.yml

@@ -31,6 +31,20 @@ jobs:
       - name: "Generate Docs"
         run: "uv run invoke generate-doc"
 
+      - name: "Setup Node.js"
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+
+      - name: "Install Node dependencies"
+        run: npm install
+        working-directory: ./docs
+
+      - name: "Build documentation"
+        run: "uv run invoke docusaurus"
+
       - name: commit docs
         uses: github-actions-x/commit@v2.9
         with:

docs/_templates/plugin.mdx.j2

@@ -5,15 +5,15 @@ description: {{ documentation.get('short_description', '') }}
 
 # {{ plugin_type.title() }} {{ plugin_type.lower() }}
 
-{% for description in documentation.get('description', '') %}{{ description }} {% endfor %}
+{% for description in documentation.get('description', '') %}{{ description | mdx_safe }} {% endfor %}
 
 {% if documentation.get('options') -%}
 ## Parameters
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 {%- for param_name, param in documentation.options.items() %}
-| `{{ param_name }}` | `{{ param.get('type', '') }}` | {{ "Yes" if param.get('required', False) else "No" }} | {{ param.get('default', '') }} | {{ param.get('description', '') if param.get('description') is string else param.get('description', [])|join(' ') }} |
+| `{{ param_name }}` | `{{ param.get('type', '') }}` | {{ "Yes" if param.get('required', False) else "No" }} | {{ param.get('default', '') }} | {{ param.get('description', '') | mdx_safe }} |
 {%- endfor %}
 {%- endif %}
 {% if examples %}
@@ -30,6 +30,6 @@ description: {{ documentation.get('short_description', '') }}
 | Key | Type | Description |
 |-----|------|-------------|
 {%- for key, data in returns.items() %}
-| `{{ key }}` | `{{ data.get('type', '') }}` | {{ data.get('description', '') if data.get('description') is string else data.get('description', [])|join(' ') }} |
+| `{{ key }}` | `{{ data.get('type', '') }}` | {{ data.get('description', '') | mdx_safe }} |
 {%- endfor %}
 {% endif %}

docs/docs/readme.mdx

@@ -30,12 +30,13 @@ These are the plugins in the `opsmill.infrahub` collection:
 
 <!-- vale off -->
 
-* [artifact_fetch](./references/plugins/artifact_fetch_module.mdx) – Fetch the content of an artifact from Infrahub
-* [schema](./references/plugins/schema_module.mdx) – Load, check, or export schemas in Infrahub
 * [node](./references/plugins/node_module.mdx) – Creates, Updates or Deletes a node in Infrahub
-* [artifact_generate](./references/plugins/artifact_generate_module.mdx) – Trigger artifact regeneration in Infrahub
-* [query_graphql](./references/plugins/query_graphql_module.mdx) – Queries and returns elements from Infrahub GraphQL API
+* [object_file_fetch](./references/plugins/object_file_fetch_module.mdx) – Fetch file content from a CoreFileObject node in Infrahub
 * [branch](./references/plugins/branch_module.mdx) – Creates, Updates or Deletes a branch in Infrahub
+* [schema](./references/plugins/schema_module.mdx) – Load, check, or export schemas in Infrahub
+* [artifact_fetch](./references/plugins/artifact_fetch_module.mdx) – Fetch the content of an artifact from Infrahub
+* [query_graphql](./references/plugins/query_graphql_module.mdx) – Queries and returns elements from Infrahub GraphQL API
+* [artifact_generate](./references/plugins/artifact_generate_module.mdx) – Trigger artifact regeneration in Infrahub
 
 <!-- vale on -->
 

docs/docs/references/plugins/node_module.mdx

@@ -19,6 +19,8 @@ Creates, Updates or Deletes a node of a given Kind in Infrahub through Infrahub
 | `branch` | `str` | No | main | Branch in which the request is made |
 | `validate_certs` | `bool` | No | True | Whether or not to validate SSL of the Infrahub instance |
 | `state` | `str` | No | present | Use C(present) or C(absent) for adding or removing. |
+| `file_path` | `str` | No | None | Local filesystem path to the file to upload when creating or updating a CoreFileObject node. Required when the kind inherits from CoreFileObject (unless C(fetch_file) is used instead). Mutually exclusive with C(fetch_file). When provided, the module computes a SHA-1 checksum and skips the upload if it matches the server-side checksum (idempotent). Fails if the kind does not inherit from CoreFileObject. Ignored in check mode (no upload performed). |
+| `fetch_file` | `bool` | No | False | When C(true), download the file content from the CoreFileObject node and include it in the result as C(binary) (base64-encoded) and C(text) (UTF-8 decoded for text MIME types, null otherwise). Required when the kind inherits from CoreFileObject and C(file_path) is not provided. Mutually exclusive with C(file_path). Ignored in check mode (no download performed). Fails if the kind does not inherit from CoreFileObject. |
 
 ## Examples
 
@@ -50,3 +52,5 @@ Creates, Updates or Deletes a node of a given Kind in Infrahub through Infrahub
 |-----|------|-------------|
 | `object` | `dict` | Serialized object as created or already existent within Infrahub |
 | `msg` | `str` | Message indicating failure or info about what has been achieved |
+| `binary` | `str` | Base64-encoded file content downloaded from the CoreFileObject node. Present only when I(fetch_file=true) and not in check mode. |
+| `text` | `str` | UTF-8 decoded file content for text MIME types (text/plain, application/json, etc.). null for binary MIME types. Present only when I(fetch_file=true) and not in check mode. |

docs/docs/references/plugins/object_file_fetch_module.mdx

@@ -0,0 +1,70 @@
+---
+title: object_file_fetch
+description: Fetch file content from a CoreFileObject node in Infrahub
+---
+
+# Modules modules
+
+Downloads the binary file content stored on a CoreFileObject schema node. Identifies the node by UUID (node_id) or HFID (hfid). Optionally saves the file to a local destination path. Returns base64-encoded binary content and metadata regardless of I(dest). 
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `api_endpoint` | `str` | No |  | Endpoint of the Infrahub API, optional env=INFRAHUB_ADDRESS |
+| `token` | `str` | No |  | The API token created through Infrahub, optional env=INFRAHUB_API_TOKEN |
+| `timeout` | `int` | No | 10 | Timeout for Infrahub requests in seconds |
+| `validate_certs` | `bool` | No | True | Whether or not to validate SSL of the Infrahub instance |
+| `branch` | `str` | No | main | Branch in which the request is made |
+| `kind` | `str` | Yes |  | Schema kind that inherits from CoreFileObject (e.g. C(NetworkCircuitContract)) |
+| `node_id` | `str` | No |  | UUID of the CoreFileObject node to fetch. One of I(node_id) or I(hfid) is required. |
+| `hfid` | `list` | No |  | Human-friendly ID component values for the CoreFileObject node. One of I(node_id) or I(hfid) is required. |
+| `dest` | `str` | No | None | Local path to save the file content. When a directory path is given (trailing slash or existing directory), the file is saved as `{dest}/{node.file_name}`. When a file path is given, the file is saved exactly at that path. When omitted, file content is returned as variables only. |
+
+## Examples
+
+```yaml
+---
+- name: Fetch contract PDF by node UUID
+  opsmill.infrahub.object_file_fetch:
+    kind: NetworkCircuitContract
+    node_id: "abc123-uuid"
+  register: fetch_result
+
+- name: Write fetched file to disk
+  ansible.builtin.copy:
+    content: "{{ fetch_result.binary | b64decode }}"
+    dest: /tmp/contract.pdf
+
+- name: Fetch and save to directory by HFID
+  opsmill.infrahub.object_file_fetch:
+    kind: NetworkCircuitContract
+    hfid:
+      - "contract.pdf"
+    dest: /tmp/contracts/
+  register: fetch_result
+# File saved to /tmp/contracts/contract.pdf
+# fetch_result.dest == "/tmp/contracts/contract.pdf"
+
+- name: Fetch and save to explicit file path
+  opsmill.infrahub.object_file_fetch:
+    kind: NetworkCircuitContract
+    node_id: "abc123-uuid"
+    dest: /tmp/my-contract.pdf
+  register: fetch_result
+# File saved to exactly /tmp/my-contract.pdf
+```
+
+## Return values
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `binary` | `str` | Base64-encoded file content downloaded from the CoreFileObject node. |
+| `text` | `str` | UTF-8 decoded file content for text MIME types (text/plain, application/json, etc.). null for binary MIME types. |
+| `file_name` | `str` | Original filename as stored in Infrahub. |
+| `file_type` | `str` | MIME type of the file as detected by Infrahub. |
+| `file_size` | `int` | Size of the file in bytes. |
+| `checksum` | `str` | SHA-1 hex digest of the file content as stored in Infrahub. |
+| `node_id` | `str` | UUID of the fetched CoreFileObject node. |
+| `dest` | `str` | Resolved local path where the file was saved. null if I(dest) was not provided. |
+| `msg` | `str` | Status message. |

galaxy.yml

@@ -10,7 +10,7 @@ namespace: opsmill
 name: infrahub
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 1.8.0
+version: 1.8.1
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

plugins/modules/object_file_fetch.py

@@ -72,7 +72,7 @@
         description:
             - Local path to save the file content.
             - When a directory path is given (trailing slash or existing directory),
-              the file is saved as C({dest}/{node.file_name}).
+              the file is saved as `{dest}/{node.file_name}`.
             - When a file path is given, the file is saved exactly at that path.
             - When omitted, file content is returned as variables only.
         type: str

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "infrahub_ansible_modules"
-version = "1.8.0"
+version = "1.8.1"
 description = "Ansible collection to interact with Infrahub's API"
 authors = [{name = "OpsMill", email = "info@opsmill.com"}]
 license = {text = "GPLv3"}

tasks/docs.py

@@ -1,12 +1,34 @@
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 from typing import Any, NamedTuple
 
 import yaml
 from invoke import Context, task
 
+# Splits text on Markdown inline code spans (single backticks) so MDX-escaping
+# only runs on prose, not on code spans where `{var}` is already safe.
+_CODE_SPAN_RE = re.compile(r"(`[^`]+`)")
+
+
+def mdx_safe(value: object) -> str:
+    """Render a docstring description as MDX-safe text.
+
+    Joins list-style descriptions into one line and escapes JSX-reserved braces
+    that appear outside Markdown code spans, preventing MDX from interpreting
+    placeholders like ``{var}`` as JSX expressions referencing undefined names.
+    """
+    if value is None:
+        return ""
+    text = " ".join(str(item) for item in value) if isinstance(value, list) else str(value)
+    parts = _CODE_SPAN_RE.split(text)
+    return "".join(
+        part if index % 2 == 1 else part.replace("{", r"\{").replace("}", r"\}") for index, part in enumerate(parts)
+    )
+
+
 MAIN_DIRECTORY = "."
 NAMESPACE = "INFRAHUB-ANSIBLE-DOCS"
 
@@ -228,6 +250,7 @@ def generate_docs(context: Context, debug: bool = False, plugin_type: str | None
         trim_blocks=False,
         lstrip_blocks=True,
     )
+    environment.filters["mdx_safe"] = mdx_safe
 
     plugin_template = environment.from_string((template_dir / "plugin.mdx.j2").read_text())
     readme_template = environment.from_string((template_dir / "readme.mdx.j2").read_text())