From 789a876a086586697bef63b41960b1adce0e3f63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= <dan@kosli.com>
Date: Thu, 23 Apr 2026 13:06:34 +0200
Subject: [PATCH] fix: update CLI nav script to target config/navigation.json

The script was writing to docs.json, but navigation moved to
config/navigation.json via $ref. The script silently found no
matching structure and wrote docs.json back unchanged.

Changes:
- Script now reads/writes config/navigation.json directly
- Errors if CLI Reference section is not found (no more silent failure)
- Workflow updated to pass --nav-file config/navigation.json
- Renamed --config flag to --nav-file for clarity

Closes #174
---
 .github/workflows/update-cli-docs.yml |  4 +-
 scripts/update-cli-nav.py             | 74 +++++++++++++++------------
 2 files changed, 42 insertions(+), 36 deletions(-)

diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml
index 726cb48..e955924 100644
--- a/.github/workflows/update-cli-docs.yml
+++ b/.github/workflows/update-cli-docs.yml
@@ -59,8 +59,8 @@ jobs:
           TAG="${{ steps.tag.outputs.cli_tag }}"
           sed -i "s/\*\*v[0-9][0-9.]*\*\*/**${TAG}**/" client_reference/overview.md
 
-      - name: Update CLI navigation in docs.json
-        run: python scripts/update-cli-nav.py --docs-dir client_reference/ --config docs.json
+      - name: Update CLI navigation
+        run: python scripts/update-cli-nav.py --docs-dir client_reference/ --nav-file config/navigation.json
 
       - name: Install helm-docs
         run: |
diff --git a/scripts/update-cli-nav.py b/scripts/update-cli-nav.py
index 8754b87..cc251f5 100644
--- a/scripts/update-cli-nav.py
+++ b/scripts/update-cli-nav.py
@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 """
-Update the CLI Reference navigation in docs.json based on files in client_reference/.
+Update the CLI Reference navigation in config/navigation.json based on files in client_reference/.
 
 Usage:
-    python scripts/update-cli-nav.py --docs-dir client_reference/ --config docs.json
+    python scripts/update-cli-nav.py --docs-dir client_reference/ --nav-file config/navigation.json
 """
 
 import argparse
@@ -159,39 +159,45 @@ def build_nav_groups(docs_dir):
     return nav_groups
 
 
-def update_docs_json(config_path, nav_groups):
-    """Update the CLI Reference section in docs.json."""
-    with open(config_path, 'r', encoding='utf-8') as f:
-        config = json.load(f)
-
-    # Find the Reference tab and CLI Reference menu item
-    for product in config.get('navigation', {}).get('products', []):
-        for tab in product.get('tabs', []):
-            if tab.get('tab') == 'Reference':
-                menu = tab.get('menu', [])
-                for item in menu:
-                    if item.get('item') == 'CLI Reference':
-                        item['groups'] = nav_groups
-                        break
-                else:
-                    # CLI Reference not found, add it
-                    menu.insert(0, {
-                        'item': 'CLI Reference',
-                        'icon': 'terminal',
-                        'groups': nav_groups,
-                    })
-                break
-
-    with open(config_path, 'w', encoding='utf-8') as f:
-        json.dump(config, f, indent=2, ensure_ascii=False)
+def update_navigation(nav_path, nav_groups):
+    """Update the CLI Reference section in config/navigation.json."""
+    with open(nav_path, 'r', encoding='utf-8') as f:
+        nav = json.load(f)
+
+    updated = False
+
+    # navigation.json structure: { "tabs": [ { "tab": "Reference", "menu": [...] } ] }
+    for tab in nav.get('tabs', []):
+        if tab.get('tab') == 'Reference':
+            menu = tab.get('menu', [])
+            for item in menu:
+                if item.get('item') == 'CLI Reference':
+                    item['groups'] = nav_groups
+                    updated = True
+                    break
+            else:
+                menu.insert(0, {
+                    'item': 'CLI Reference',
+                    'icon': 'terminal',
+                    'groups': nav_groups,
+                })
+                updated = True
+            break
+
+    if not updated:
+        print(f'Error: Could not find CLI Reference in {nav_path}', file=sys.stderr)
+        sys.exit(1)
+
+    with open(nav_path, 'w', encoding='utf-8') as f:
+        json.dump(nav, f, indent=2, ensure_ascii=False)
         f.write('\n')
 
-    print(f'Updated {config_path} with {len(nav_groups)} CLI groups')
+    print(f'Updated {nav_path} with {len(nav_groups)} CLI groups')
 
 
 def main():
     parser = argparse.ArgumentParser(
-        description='Update CLI Reference navigation in docs.json'
+        description='Update CLI Reference navigation in config/navigation.json'
     )
     parser.add_argument(
         '--docs-dir',
@@ -199,9 +205,9 @@ def main():
         help='Directory containing CLI reference markdown files',
     )
     parser.add_argument(
-        '--config',
+        '--nav-file',
         required=True,
-        help='Path to docs.json config file',
+        help='Path to config/navigation.json',
     )
     args = parser.parse_args()
 
@@ -209,8 +215,8 @@ def main():
         print(f'Error: Directory {args.docs_dir} does not exist')
         sys.exit(1)
 
-    if not os.path.isfile(args.config):
-        print(f'Error: Config file {args.config} does not exist')
+    if not os.path.isfile(args.nav_file):
+        print(f'Error: Navigation file {args.nav_file} does not exist')
         sys.exit(1)
 
     nav_groups = build_nav_groups(args.docs_dir)
@@ -218,7 +224,7 @@ def main():
     for group in nav_groups:
         print(f"  {group['group']}: {len(group['pages'])} pages")
 
-    update_docs_json(args.config, nav_groups)
+    update_navigation(args.nav_file, nav_groups)
 
 
 if __name__ == '__main__':