@kanopi/wp-ai-indexer 1.0.0

package/.circleci/setup-node.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+#
+# Node.js Setup Script
+#
+# Description:
+#   Installs Node.js if not already present, or validates existing installation.
+#
+# Usage:
+#   setup-node.sh [OPTIONS]
+#
+# Options:
+#   --version VERSION         Node.js major version to install (default: 22)
+#   --skip-if-installed       Skip installation if Node.js is already installed
+#   --validate-version        Ensure installed version matches requested version
+#   --dry-run                 Show what would be done without executing
+#   --help                    Show this help message
+#
+# Exit Codes:
+#   0 - Node.js is installed and validated
+#   1 - Installation failed
+#   2 - Invalid arguments or version mismatch
+#
+
+set -eo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Default values
+NODE_VERSION="22"
+SKIP_IF_INSTALLED="false"
+VALIDATE_VERSION="false"
+DRY_RUN="false"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --version)
+            NODE_VERSION="$2"
+            shift 2
+            ;;
+        --skip-if-installed)
+            SKIP_IF_INSTALLED="true"
+            shift
+            ;;
+        --validate-version)
+            VALIDATE_VERSION="true"
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN="true"
+            shift
+            ;;
+        --help)
+            grep '^#' "$0" | grep -v '#!/bin/bash' | sed 's/^# //;s/^#//'
+            exit 0
+            ;;
+        *)
+            echo -e "${RED}Error: Unknown option $1${NC}"
+            echo "Use --help for usage information"
+            exit 2
+            ;;
+    esac
+done
+
+# Helper functions
+log_header() {
+    echo -e "\n${BLUE}========================================${NC}"
+    echo -e "${BLUE}$1${NC}"
+    echo -e "${BLUE}========================================${NC}"
+}
+
+log_success() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+log_info() {
+    echo -e "${BLUE}ℹ${NC} $1"
+}
+
+# Validate version format
+if [[ ! "$NODE_VERSION" =~ ^[0-9]+$ ]]; then
+    log_error "Invalid Node.js version: $NODE_VERSION (must be a number like 18, 20, 22)"
+    exit 2
+fi
+
+log_header "Node.js Setup"
+log_info "Requested version: $NODE_VERSION.x"
+log_info "Dry run: $DRY_RUN"
+
+# Check if Node.js is already installed
+if command -v node &> /dev/null; then
+    INSTALLED_VERSION=$(node --version | sed 's/v//' | cut -d. -f1)
+    log_info "Node.js is already installed: $(node --version)"
+    log_info "npm version: $(npm --version)"
+
+    if [[ "$VALIDATE_VERSION" == "true" ]]; then
+        if [[ "$INSTALLED_VERSION" != "$NODE_VERSION" ]]; then
+            log_warning "Installed version (v$INSTALLED_VERSION) doesn't match requested version (v$NODE_VERSION)"
+
+            if [[ "$SKIP_IF_INSTALLED" == "true" ]]; then
+                log_info "Skipping installation due to --skip-if-installed flag"
+                log_success "Using existing Node.js installation"
+                exit 0
+            else
+                log_info "Proceeding with installation of Node.js $NODE_VERSION.x..."
+            fi
+        else
+            log_success "Installed version matches requested version"
+            exit 0
+        fi
+    else
+        if [[ "$SKIP_IF_INSTALLED" == "true" ]]; then
+            log_success "Node.js is already installed, skipping"
+            exit 0
+        else
+            log_info "Node.js is installed but will reinstall as requested"
+        fi
+    fi
+else
+    log_info "Node.js not found, installing..."
+fi
+
+# Detect OS and package manager
+if [[ "$DRY_RUN" == "true" ]]; then
+    log_info "[DRY RUN] Would detect OS and install Node.js $NODE_VERSION.x"
+    exit 0
+fi
+
+log_header "Installing Node.js $NODE_VERSION.x"
+
+# Detect OS
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    log_info "Detected Linux OS"
+
+    # Check if running Debian/Ubuntu
+    if command -v apt-get &> /dev/null; then
+        log_info "Using apt package manager"
+
+        # Download and run NodeSource setup script
+        log_info "Downloading NodeSource setup script..."
+        curl -fsSL "https://deb.nodesource.com/setup_${NODE_VERSION}.x" -o /tmp/nodesource_setup.sh
+
+        log_info "Running NodeSource setup script..."
+        sudo bash /tmp/nodesource_setup.sh
+        rm /tmp/nodesource_setup.sh
+
+        log_info "Installing Node.js via apt..."
+        sudo apt-get install -y nodejs
+
+    # Check if running RedHat/CentOS/Fedora
+    elif command -v yum &> /dev/null; then
+        log_info "Using yum package manager"
+
+        # Download and run NodeSource setup script
+        log_info "Downloading NodeSource setup script..."
+        curl -fsSL "https://rpm.nodesource.com/setup_${NODE_VERSION}.x" -o /tmp/nodesource_setup.sh
+
+        log_info "Running NodeSource setup script..."
+        sudo bash /tmp/nodesource_setup.sh
+        rm /tmp/nodesource_setup.sh
+
+        log_info "Installing Node.js via yum..."
+        sudo yum install -y nodejs
+
+    else
+        log_error "Unsupported Linux distribution (no apt or yum found)"
+        exit 1
+    fi
+
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+    log_info "Detected macOS"
+
+    if command -v brew &> /dev/null; then
+        log_info "Installing via Homebrew..."
+        brew install node@${NODE_VERSION}
+
+        # Link the installed version
+        brew link --overwrite node@${NODE_VERSION}
+    else
+        log_error "Homebrew not found. Please install Homebrew first: https://brew.sh"
+        exit 1
+    fi
+
+else
+    log_error "Unsupported operating system: $OSTYPE"
+    exit 1
+fi
+
+# Validate installation
+log_header "Validating Installation"
+
+if command -v node &> /dev/null; then
+    INSTALLED_VERSION=$(node --version | sed 's/v//' | cut -d. -f1)
+    log_success "Node.js installed: $(node --version)"
+    log_success "npm version: $(npm --version)"
+
+    if [[ "$VALIDATE_VERSION" == "true" ]]; then
+        if [[ "$INSTALLED_VERSION" != "$NODE_VERSION" ]]; then
+            log_warning "Installed version (v$INSTALLED_VERSION) doesn't match requested version (v$NODE_VERSION)"
+            log_warning "This may be acceptable if the system provided a compatible version"
+        else
+            log_success "Version validation passed"
+        fi
+    fi
+
+    exit 0
+else
+    log_error "Node.js installation failed - node command not found"
+    exit 1
+fi

package/.circleci/test-package.sh

@@ -0,0 +1,247 @@
+#!/bin/bash
+#
+# Node Package Testing Script
+#
+# Description:
+#   Runs tests for Node.js packages with dependency caching and parallel execution support.
+#
+# Usage:
+#   test-package.sh [OPTIONS] PACKAGE_PATH
+#
+# Arguments:
+#   PACKAGE_PATH              Path to the package (e.g., packages/wp-ai-indexer)
+#
+# Options:
+#   --cache-key KEY           Custom cache key prefix (default: v1-package-deps)
+#   --max-workers NUM         Number of parallel test workers (default: 2)
+#   --test-command CMD        npm test command to run (default: test:ci)
+#   --skip-cache              Skip cache restoration and saving
+#   --store-results           Store test results in CircleCI (default: true in CI)
+#   --results-path PATH       Path to store test results (default: {package}/coverage)
+#   --dry-run                 Show what would be done without executing
+#   --help                    Show this help message
+#
+# Exit Codes:
+#   0 - Tests passed
+#   1 - Tests failed or execution error
+#   2 - Invalid arguments
+#
+
+set -eo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Default values
+PACKAGE_PATH=""
+CACHE_KEY="v1-package-deps"
+MAX_WORKERS="2"
+TEST_COMMAND="test:ci"
+SKIP_CACHE="false"
+STORE_RESULTS="${CIRCLECI:-false}"
+RESULTS_PATH=""
+DRY_RUN="false"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --cache-key)
+            CACHE_KEY="$2"
+            shift 2
+            ;;
+        --max-workers)
+            MAX_WORKERS="$2"
+            shift 2
+            ;;
+        --test-command)
+            TEST_COMMAND="$2"
+            shift 2
+            ;;
+        --skip-cache)
+            SKIP_CACHE="true"
+            shift
+            ;;
+        --store-results)
+            STORE_RESULTS="true"
+            shift
+            ;;
+        --results-path)
+            RESULTS_PATH="$2"
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN="true"
+            shift
+            ;;
+        --help)
+            grep '^#' "$0" | grep -v '#!/bin/bash' | sed 's/^# //;s/^#//'
+            exit 0
+            ;;
+        -*)
+            echo -e "${RED}Error: Unknown option $1${NC}"
+            echo "Use --help for usage information"
+            exit 2
+            ;;
+        *)
+            PACKAGE_PATH="$1"
+            shift
+            ;;
+    esac
+done
+
+# Helper functions
+log_header() {
+    echo -e "\n${BLUE}========================================${NC}"
+    echo -e "${BLUE}$1${NC}"
+    echo -e "${BLUE}========================================${NC}"
+}
+
+log_success() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+log_info() {
+    echo -e "${BLUE}ℹ${NC} $1"
+}
+
+# Validate required parameters
+if [[ -z "$PACKAGE_PATH" ]]; then
+    log_error "Package path is required"
+    echo "Usage: $0 [OPTIONS] PACKAGE_PATH"
+    exit 2
+fi
+
+if [[ ! -d "$PACKAGE_PATH" ]]; then
+    log_error "Package path does not exist: $PACKAGE_PATH"
+    exit 2
+fi
+
+if [[ ! -f "$PACKAGE_PATH/package.json" ]]; then
+    log_error "No package.json found in $PACKAGE_PATH"
+    exit 2
+fi
+
+# Set default results path if not specified
+if [[ -z "$RESULTS_PATH" ]]; then
+    RESULTS_PATH="$PACKAGE_PATH/coverage"
+fi
+
+log_header "Node Package Testing"
+log_info "Package: $PACKAGE_PATH"
+log_info "Max workers: $MAX_WORKERS"
+log_info "Test command: npm run $TEST_COMMAND"
+log_info "Dry run: $DRY_RUN"
+
+# Restore cache (if in CircleCI and cache enabled)
+if [[ "$SKIP_CACHE" == "false" ]] && [[ -n "${CIRCLECI:-}" ]]; then
+    log_header "Restoring Cache"
+    if [[ "$DRY_RUN" == "false" ]]; then
+        # CircleCI cache restoration would happen via CircleCI's restore_cache step
+        # This script focuses on the execution logic
+        log_info "Cache restoration handled by CircleCI"
+        log_info "Cache keys:"
+        log_info "  - ${CACHE_KEY}-{{ checksum \"$PACKAGE_PATH/package-lock.json\" }}"
+        log_info "  - ${CACHE_KEY}-{{ .Branch }}-"
+        log_info "  - ${CACHE_KEY}-main-"
+        log_info "  - ${CACHE_KEY}-"
+    else
+        log_info "[DRY RUN] Would restore cache with key: $CACHE_KEY"
+    fi
+fi
+
+# Install dependencies
+log_header "Installing Dependencies"
+if [[ "$DRY_RUN" == "false" ]]; then
+    cd "$PACKAGE_PATH"
+
+    # Use npm ci for clean, reproducible installs
+    if [[ -f "package-lock.json" ]]; then
+        log_info "Running npm ci..."
+        npm ci
+        log_success "Dependencies installed"
+    else
+        log_info "No package-lock.json found, running npm install..."
+        npm install
+        log_success "Dependencies installed"
+    fi
+
+    cd - > /dev/null
+else
+    log_info "[DRY RUN] Would run: cd $PACKAGE_PATH && npm ci"
+fi
+
+# Save cache (if in CircleCI and cache enabled)
+if [[ "$SKIP_CACHE" == "false" ]] && [[ -n "${CIRCLECI:-}" ]]; then
+    log_header "Saving Cache"
+    if [[ "$DRY_RUN" == "false" ]]; then
+        # CircleCI cache saving would happen via CircleCI's save_cache step
+        log_info "Cache saving handled by CircleCI"
+        log_info "Cache paths:"
+        log_info "  - $PACKAGE_PATH/node_modules"
+        log_info "  - ~/.npm"
+        log_info "  - ~/.cache"
+    else
+        log_info "[DRY RUN] Would save cache to: $CACHE_KEY"
+    fi
+fi
+
+# Run tests
+log_header "Running Tests"
+if [[ "$DRY_RUN" == "false" ]]; then
+    cd "$PACKAGE_PATH"
+
+    # Check if test command exists in package.json
+    if ! npm run | grep -q "$TEST_COMMAND"; then
+        log_error "Test command '$TEST_COMMAND' not found in package.json"
+        exit 1
+    fi
+
+    # Run tests with specified max workers
+    log_info "Executing: npm run $TEST_COMMAND -- --maxWorkers=$MAX_WORKERS"
+    if npm run "$TEST_COMMAND" -- --maxWorkers="$MAX_WORKERS"; then
+        log_success "Tests passed"
+        TEST_RESULT=0
+    else
+        log_error "Tests failed"
+        TEST_RESULT=1
+    fi
+
+    cd - > /dev/null
+else
+    log_info "[DRY RUN] Would run: npm run $TEST_COMMAND -- --maxWorkers=$MAX_WORKERS"
+    TEST_RESULT=0
+fi
+
+# Store test results and artifacts (if in CircleCI)
+if [[ "$STORE_RESULTS" == "true" ]] && [[ -n "${CIRCLECI:-}" ]]; then
+    log_header "Storing Test Results"
+    if [[ "$DRY_RUN" == "false" ]]; then
+        if [[ -d "$RESULTS_PATH" ]]; then
+            log_success "Test results available at: $RESULTS_PATH"
+            log_info "Store test results handled by CircleCI"
+            log_info "  - store_test_results: $RESULTS_PATH"
+            log_info "  - store_artifacts: $RESULTS_PATH"
+        else
+            log_info "No test results found at $RESULTS_PATH"
+        fi
+    else
+        log_info "[DRY RUN] Would store test results from: $RESULTS_PATH"
+    fi
+fi
+
+log_header "Testing Complete"
+if [[ $TEST_RESULT -eq 0 ]]; then
+    log_success "All tests passed"
+else
+    log_error "Tests failed"
+fi
+
+exit $TEST_RESULT

package/.eslintrc.js

@@ -0,0 +1,52 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json',
+  },
+  plugins: ['@typescript-eslint', 'prettier'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    'prettier',
+  ],
+  rules: {
+    // TypeScript-specific rules
+    '@typescript-eslint/explicit-function-return-type': [
+      'warn',
+      {
+        allowExpressions: true,
+        allowTypedFunctionExpressions: true,
+      },
+    ],
+    '@typescript-eslint/no-unused-vars': [
+      'error',
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/await-thenable': 'error',
+
+    // General code quality
+    'no-console': ['warn', { allow: ['warn', 'error'] }],
+    'prefer-const': 'error',
+    'no-var': 'error',
+    'eqeqeq': ['error', 'always'],
+    'curly': ['error', 'all'],
+
+    // Prettier integration
+    'prettier/prettier': 'error',
+  },
+  env: {
+    node: true,
+    es2020: true,
+  },
+  ignorePatterns: ['dist', 'node_modules', 'coverage', '*.js', '!.eslintrc.js'],
+};

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanopi Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.