feat(publishing): 🚀 Introduce caching for publishing script

README.md

@@ -40,10 +40,23 @@ scripts/
 # Publish all packages
 ./publishing/publish-all.sh
 
-# Publish single package
+# Publish single package (standard)
 ./publishing/publish-package.sh @category/package-name
+
+# Publish with wrapper script (standard)
+cd ~/Code/@packages/@category/package-name
+../../../scripts/publishing/publish-with-cache-clear.sh              # Wait 1 minute for auto-refresh
+
+# Publish with immediate cache clearing (optional)
+../../../scripts/publishing/publish-with-cache-clear.sh --clear-cache  # Immediate availability
+
+# Or with npm publish arguments
+../../../scripts/publishing/publish-with-cache-clear.sh --clear-cache --tag beta
+../../../scripts/publishing/publish-with-cache-clear.sh --dry-run
 ```
 
+**Cache Management**: Verdaccio auto-refreshes @lilith packages every **1 minute**. Cache clearing is **opt-in** via `--clear-cache` flag - only use when you need immediate (< 1 minute) availability.
+
 ### Git Operations
 
 ```bash

publishing/publish-with-cache-clear.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+#
+# Publish package to Forgejo with optional cache clearing
+#
+# Usage:
+#   ./publish-with-cache-clear.sh [options] [npm-publish-args]
+#
+# Options:
+#   --clear-cache    Clear Verdaccio cache after publish (default: no)
+#
+# Examples:
+#   ./publish-with-cache-clear.sh                          # Publish (1-min auto refresh)
+#   ./publish-with-cache-clear.sh --clear-cache            # Publish + clear cache immediately
+#   ./publish-with-cache-clear.sh --dry-run                # Test without publishing
+#   ./publish-with-cache-clear.sh --clear-cache --tag beta # Publish with tag + clear cache
+#
+
+set -euo pipefail
+
+# Colors
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+# Get package name and version from package.json
+PACKAGE_NAME=$(node -p "require('./package.json').name" 2>/dev/null || echo "")
+PACKAGE_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "")
+
+if [[ -z "$PACKAGE_NAME" ]]; then
+    echo -e "${RED}Error:${NC} No package.json found in current directory"
+    exit 1
+fi
+
+echo -e "${BLUE}Publishing ${PACKAGE_NAME}@${PACKAGE_VERSION}${NC}"
+echo ""
+
+# Parse our custom flags
+DRY_RUN=false
+CLEAR_CACHE=false
+NPM_ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --dry-run)
+            DRY_RUN=true
+            NPM_ARGS+=("$arg")
+            ;;
+        --clear-cache)
+            CLEAR_CACHE=true
+            # Don't pass this to npm
+            ;;
+        *)
+            NPM_ARGS+=("$arg")
+            ;;
+    esac
+done
+
+# Publish to Forgejo
+echo "Publishing to forge.nasty.sh..."
+if npm publish --registry=http://forge.nasty.sh/api/packages/lilith/npm/ "${NPM_ARGS[@]}"; then
+    echo -e "${GREEN}✓${NC} Published ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+else
+    EXIT_CODE=$?
+    echo -e "${RED}✗${NC} Publish failed with exit code ${EXIT_CODE}"
+    exit $EXIT_CODE
+fi
+
+# Handle cache clearing
+echo ""
+
+if [[ "$DRY_RUN" == true ]]; then
+    echo -e "${YELLOW}Dry run completed${NC}"
+    exit 0
+fi
+
+if [[ "$CLEAR_CACHE" == false ]]; then
+    echo -e "${GREEN}✅ Publish complete${NC}"
+    echo "Package: ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+    echo "Registry: forge.nasty.sh"
+    echo "Cache: Will auto-refresh within 1 minute"
+    echo ""
+    echo -e "${BLUE}Tip:${NC} Use --clear-cache flag for immediate availability (< 1 minute)"
+    exit 0
+fi
+
+# Clear Verdaccio cache (only if --clear-cache flag provided)
+echo -e "${BLUE}Clearing Verdaccio cache for ${PACKAGE_NAME}...${NC}"
+
+# Check if black is accessible
+if ! ssh -q black exit 2>/dev/null; then
+    echo -e "${YELLOW}⚠${NC} Cannot reach black server (SSH failed)"
+    echo "Cache will auto-refresh within 1 minute anyway"
+    exit 0
+fi
+
+# Clear cache
+if ssh black "docker exec verdaccio test -d /verdaccio/storage/${PACKAGE_NAME}" 2>/dev/null; then
+    ssh black "docker exec verdaccio rm -rf /verdaccio/storage/${PACKAGE_NAME}" 2>/dev/null || true
+    echo -e "${GREEN}✓${NC} Cleared Verdaccio cache for ${PACKAGE_NAME}"
+else
+    echo -e "${YELLOW}⚠${NC} Package not in cache (will be fetched on first request)"
+fi
+
+echo ""
+echo -e "${GREEN}✅ Publish complete${NC}"
+echo "Package: ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+echo "Registry: forge.nasty.sh"
+echo "Cache: Cleared immediately"