Merge production into v0.2.0

.github/scripts/convert_markdown_links.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+import sys
+import re
+import os
+from pathlib import Path
+
+# Regex patterns
+REF_DEF_RE = re.compile(r"^\[([^\]]+)\]:\s*(\S.*)$")
+EXPLICIT_LINK_RE = re.compile(r"\[([^\]]+)\]\[([^\]]+)\]")
+IMPLICIT_LINK_RE = re.compile(r"\[([^\]]+)\]\[\]")
+BARE_LINK_RE = re.compile(r"\[([^\]]+)\](?!\()")
+COMMENT_LINE_RE = re.compile(r"^\s*<!--.*-->\s*$")
+
+def convert_markdown_links(file_path):
+    with open(file_path, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+
+    # First pass: collect reference definitions and their line numbers
+    refs = {}
+    ref_lines = set()
+    content_lines = []
+    for i, line in enumerate(lines):
+        m = REF_DEF_RE.match(line.strip())
+        if m:
+            ref_id, url = m.groups()
+            refs[ref_id] = url.strip()
+            ref_lines.add(i)
+        else:
+            content_lines.append((i, line))
+
+    # Convert content lines to string
+    content = ''.join(line for _, line in content_lines)
+
+    # Replace [text][ref]
+    def repl_explicit(match):
+        text, ref = match.groups()
+        url = refs.get(ref)
+        return f'[{text}]({url})' if url else match.group(0)
+    content = EXPLICIT_LINK_RE.sub(repl_explicit, content)
+
+    # Replace [text][]
+    def repl_implicit(match):
+        text = match.group(1)
+        url = refs.get(text)
+        return f'[{text}]({url})' if url else match.group(0)
+    content = IMPLICIT_LINK_RE.sub(repl_implicit, content)
+
+    # Replace [text] (bare, not followed by '(')
+    def repl_bare(match):
+        text = match.group(1)
+        url = refs.get(text)
+        return f'[{text}]({url})' if url else match.group(0)
+    content = BARE_LINK_RE.sub(repl_bare, content)
+
+    # Split content back into lines
+    new_lines = content.splitlines(True)
+
+    # Remove reference lines and clean up trailing empty/comment lines
+    final_lines = []
+    in_reference_section = False
+    for i, line in enumerate(new_lines):
+        if i in ref_lines:
+            in_reference_section = True
+            continue
+        if in_reference_section:
+            if line.strip() and not COMMENT_LINE_RE.match(line):
+                in_reference_section = False
+                final_lines.append(line)
+        else:
+            final_lines.append(line)
+
+    # Remove trailing empty lines and comments
+    while final_lines and (not final_lines[-1].strip() or COMMENT_LINE_RE.match(final_lines[-1])):
+        final_lines.pop()
+
+    # Add exactly one newline at the end
+    final_content = ''.join(final_lines).rstrip() + '\n\n'
+
+    # Write back if changed
+    if final_content != ''.join(lines):
+        with open(file_path, 'w', encoding='utf-8') as f:
+            f.write(final_content)
+        print(f"Updated {file_path}")
+    else:
+        print(f"No changes in {file_path}")
+
+def process_path(path):
+    path = Path(path)
+    if path.is_file():
+        if path.suffix == '.md':
+            convert_markdown_links(path)
+        else:
+            print(f"Skipping non-markdown file: {path}")
+    elif path.is_dir():
+        print(f"Processing directory: {path}")
+        for md_file in path.rglob('*.md'):
+            convert_markdown_links(md_file)
+    else:
+        print(f"Warning: Path '{path}' does not exist, skipping...")
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python convert-markdown-links.py <path1> [path2] ...")
+        sys.exit(1)
+    for path in sys.argv[1:]:
+        process_path(path)
+
+if __name__ == "__main__":
+    main()  

.github/scripts/get-added-files.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Get the base branch from the first argument
+BASE_BRANCH=$1
+
+# Fetch the base branch
+git fetch origin $BASE_BRANCH
+
+# Get list of added markdown files
+ADDED_FILES=$(git diff --diff-filter=A --name-only origin/$BASE_BRANCH... | grep '\.md$' || true)
+
+echo "Added files: $ADDED_FILES"
+
+# Set environment variable for added files
+if [ -n "$ADDED_FILES" ]; then
+  echo "files<<EOF" >> $GITHUB_ENV
+  echo "$ADDED_FILES" >> $GITHUB_ENV
+  echo "EOF" >> $GITHUB_ENV
+else
+  echo "files=" >> $GITHUB_ENV
+fi 

.github/scripts/update-summary.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+SUMMARY_FILE="SUMMARY.md"
+SECTION_TITLE="## Looking for a home"
+
+if [ ! -f "$SUMMARY_FILE" ]; then
+  echo "SUMMARY.md not found!"
+  exit 1
+fi
+
+if [ -z "$files" ]; then
+  echo "No new markdown files detected."
+  exit 0
+fi
+
+# Track new entries
+NEW_ENTRIES=""
+
+# Find uncategorized files
+UNLISTED_FILES=""
+for file in $files; do
+  if ! grep -q "($file)" "$SUMMARY_FILE"; then
+    UNLISTED_FILES+="$file"$'\n'
+  fi
+done
+
+# If there are uncategorized files, add them
+if [ -n "$UNLISTED_FILES" ]; then
+  # Add section if it does not already exist
+  if ! grep -Fxq "$SECTION_TITLE" "$SUMMARY_FILE"; then
+    echo -e "\n$SECTION_TITLE\n" >> "$SUMMARY_FILE"
+  fi
+
+  # Add new files under "Looking for a home"
+  for file in $UNLISTED_FILES; do
+    ENTRY="* [$file]($file)"
+    echo "$ENTRY" >> "$SUMMARY_FILE"
+    NEW_ENTRIES+="$ENTRY"$'\n'
+  done
+fi
+
+echo "Updated SUMMARY.md:"
+cat "$SUMMARY_FILE"
+
+# Save new entries as environment variable for later
+echo "new_entries<<EOF" >> $GITHUB_ENV
+echo "$NEW_ENTRIES" >> $GITHUB_ENV
+echo "EOF" >> $GITHUB_ENV 

.github/workflows/add_new_files_summary.yml

@@ -3,8 +3,9 @@ name: Update SUMMARY.md on PR
 on:
   pull_request:
     branches:
-      - main
-    types: [opened, synchronize, reopened]
+      - staging
+    types: [opened, reopened]
+
 permissions:
   contents: write
   pull-requests: write
@@ -28,70 +29,10 @@ jobs:
 
       - name: Get list of added files
         id: added_files
-        run: |
-          BASE_BRANCH=${{ github.event.pull_request.base.ref }}
-          git fetch origin $BASE_BRANCH
-          ADDED_FILES=$(git diff --diff-filter=A --name-only origin/$BASE_BRANCH... | grep '\.md$' || true)
-
-          echo "Added files: $ADDED_FILES"
-
-          if [ -n "$ADDED_FILES" ]; then
-            echo "files<<EOF" >> $GITHUB_ENV
-            echo "$ADDED_FILES" >> $GITHUB_ENV
-            echo "EOF" >> $GITHUB_ENV
-          else
-            echo "files=" >> $GITHUB_ENV
-          fi
-
+        run: .github/scripts/get-added-files.sh ${{ github.event.pull_request.base.ref }}
 
       - name: Update SUMMARY.md
-        run: |
-          SUMMARY_FILE="SUMMARY.md"
-          SECTION_TITLE="## Looking for a home"
-
-          if [ ! -f "$SUMMARY_FILE" ]; then
-            echo "SUMMARY.md not found!"
-            exit 1
-          fi
-
-          if [ -z "$files" ]; then
-            echo "No new markdown files detected."
-            exit 0
-          fi
-
-          # Track new entries
-          NEW_ENTRIES=""
-
-          # Find uncategorized files
-          UNLISTED_FILES=""
-          for file in $files; do
-            if ! grep -q "($file)" "$SUMMARY_FILE"; then
-              UNLISTED_FILES+="$file"$'\n'
-            fi
-          done
-
-          # If there are uncategorized files, add them
-          if [ -n "$UNLISTED_FILES" ]; then
-            # Add section if it does not already exist
-            if ! grep -Fxq "$SECTION_TITLE" "$SUMMARY_FILE"; then
-              echo -e "\n$SECTION_TITLE\n" >> "$SUMMARY_FILE"
-            fi
-
-            # Add new files under "Looking for a home"
-            for file in $UNLISTED_FILES; do
-              ENTRY="* [$file]($file)"
-              echo "$ENTRY" >> "$SUMMARY_FILE"
-              NEW_ENTRIES+="$ENTRY"$'\n'
-            done
-          fi
-
-          echo "Updated SUMMARY.md:"
-          cat "$SUMMARY_FILE"
-
-          # Save new entries as environment variable for later
-          echo "new_entries<<EOF" >> $GITHUB_ENV
-          echo "$NEW_ENTRIES" >> $GITHUB_ENV
-          echo "EOF" >> $GITHUB_ENV
+        run: .github/scripts/update-summary.sh
 
       - uses: crazy-max/ghaction-import-gpg@v6
         with:
@@ -117,7 +58,6 @@ jobs:
         if: env.new_entries != ''
         uses: actions/github-script@v6
         with:
-          github-token: ${{ secrets.GH_ACCESS_TOKEN }}
           script: |
             const issue_number = context.payload.pull_request.number;
             const body = `⚠️ **TODO:** These new files need to be categorized properly in \`SUMMARY.md\`!  

.github/workflows/markdown_format.yml

@@ -0,0 +1,72 @@
+name: Lint and Format Markdown
+
+on:
+  pull_request:
+    branches: [staging, production]
+
+permissions:
+  contents: write
+
+jobs:
+  lint-format:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - uses: tj-actions/changed-files@v46
+      id: changed-files
+      with:
+        files: |
+          **/*.md
+          !nexus-next/**/*.md
+          !nexus-sdk/**/*.md
+
+    - uses: DavidAnson/markdownlint-cli2-action@v20
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        config: .markdownlint.json
+        fix: true
+
+    - name: "Import GPG key"
+      id: import-gpg
+      uses: crazy-max/ghaction-import-gpg@v6
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        gpg_private_key: ${{ secrets.DEVOPS_GPG_PRIVATE_KEY }}
+        passphrase: ${{ secrets.DEVOPS_GPG_PASSPHRASE }}
+        git_user_signingkey: true
+        git_commit_gpgsign: true
+        git_config_global: true
+
+    - name: "Commit and push changes"
+      uses: stefanzweifel/git-auto-commit-action@v5
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        commit_user_name: "Talus DevOps"
+        commit_user_email: ${{ steps.import-gpg.outputs.email }}
+        commit_message: "style: format markdown files"
+
+  typos-check:
+    needs: lint-format
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - uses: tj-actions/changed-files@v46
+      id: changed-files
+      with:
+        files: |
+          **/*.md
+          !nexus-next/**/*.md
+          !nexus-sdk/**/*.md
+
+    - name: Check for typos
+      if: steps.changed-files.outputs.any_changed == 'true'
+      uses: crate-ci/typos@v1.32.0
+      with:
+        files: ${{ steps.changed-files.outputs.all_changed_files }}

.github/workflows/markdown_links.yml

@@ -0,0 +1,47 @@
+name: Format Markdown Links
+
+on:
+  pull_request:
+    branches: [staging]
+    paths:
+        - 'nexus-next/**'
+        - 'nexus-sdk/**'
+
+permissions:
+  contents: write
+
+jobs:
+  markdown-links:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Format links in markdown files
+        run: |
+          python3 .github/scripts/convert_markdown_links.py nexus-next nexus-sdk
+
+      - name: "Import GPG key"
+        id: import-gpg
+        uses: crazy-max/ghaction-import-gpg@v6
+        with:
+          gpg_private_key: ${{ secrets.DEVOPS_GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.DEVOPS_GPG_PASSPHRASE }}
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+          git_config_global: true
+
+      - name: "Commit and push changes"
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_user_name: "Talus DevOps"
+          commit_user_email: ${{ steps.import-gpg.outputs.email }}
+          commit_message: "chore(docs): format markdown links"