PSGO-268: TypeScript rewrite — Phase 0 scaffold

.dockerignore

@@ -0,0 +1,25 @@
+node_modules
+dist
+.git
+.github
+__tests__
+tests
+src/keboola_mcp_server
+3.10.venv
+3.12.venv
+.venv
+.tox
+.mypy_cache
+.pytest_cache
+*.venv
+coverage.xml
+.coverage
+test-results.xml
+feature_spec
+docs
+*.md
+!README.md
+.env
+.mcp.json
+uv.lock
+pyproject.toml

.github/actions/export-kbc-projects/action.yml

@@ -0,0 +1,30 @@
+name: 'Export kbc projects with secrets'
+description: 'Generates projects.json from .github/ci/projects.json, substituting TEST_KBC_PROJECT_* secrets'
+inputs:
+  secrets:
+    description: workflow secrets (pass `toJSON(secrets)`)
+    required: true
+outputs:
+  projects-file:
+    description: Absolute path to the generated projects.json
+    value: ${{ steps.gen.outputs.projects-file }}
+runs:
+  using: 'composite'
+  steps:
+    - name: Generate projects.json file, replace secrets
+      id: gen
+      shell: bash
+      run: |
+        # Export every TEST_KBC_PROJECT_* secret as an env var, then envsubst the template.
+        jqQuery='to_entries[] | select(.key | startswith("TEST_KBC_PROJECT_")) | "\(.key)=\(.value|tostring) "'
+        export $(
+        (jq -r -j "$jqQuery") << EndOfSecrets
+          ${{ inputs.secrets }}
+        EndOfSecrets
+        )
+
+        envsubst < .github/ci/projects.json > projects.json
+
+        # Stable mtime so test caching is not invalidated by regeneration.
+        touch -d '1970-01-01T00:00:01' projects.json
+        echo "projects-file=$(pwd)/projects.json" >> "$GITHUB_OUTPUT"

.github/ci/projects.json

@@ -0,0 +1,72 @@
+[
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 154,
+    "stagingStorage": "gcs",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_154_TOKEN"
+  },
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 1931,
+    "stagingStorage": "gcs",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_1931_TOKEN"
+  },
+  {
+    "host": "connection.keboola.com",
+    "project": 10013,
+    "stagingStorage": "s3",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_10013_TOKEN"
+  },
+  {
+    "host": "connection.keboola.com",
+    "project": 10014,
+    "stagingStorage": "s3",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_10014_TOKEN"
+  },
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 1297,
+    "stagingStorage": "gcs",
+    "backend": "bigquery",
+    "token": "$TEST_KBC_PROJECT_1297_TOKEN"
+  },
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 2832,
+    "stagingStorage": "gcs",
+    "backend": "bigquery",
+    "token": "$TEST_KBC_PROJECT_2832_TOKEN"
+  },
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 2833,
+    "stagingStorage": "gcs",
+    "backend": "bigquery",
+    "token": "$TEST_KBC_PROJECT_2833_TOKEN"
+  },
+  {
+    "host": "connection.europe-west3.gcp.keboola.com",
+    "project": 2834,
+    "stagingStorage": "gcs",
+    "backend": "bigquery",
+    "token": "$TEST_KBC_PROJECT_2834_TOKEN"
+  },
+  {
+    "host": "connection.keboola.com",
+    "project": 10166,
+    "stagingStorage": "s3",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_10166_TOKEN"
+  },
+  {
+    "host": "connection.keboola.com",
+    "project": 10169,
+    "stagingStorage": "s3",
+    "backend": "snowflake",
+    "token": "$TEST_KBC_PROJECT_10169_TOKEN"
+  }
+]

.github/workflows/ci.yml

@@ -2,183 +2,148 @@
 
 # How the CI Pipeline Works
 # - The CI workflow runs on all push events and pull requests.
-# - For pull requests from forks (coming from a different repository), we skip jobs/actions that need secrets (e.g.,
-#   publishing results, integration tests) to avoid exposing them. Only safe checks like local tests and flake8 are run.
-# - For pull requests from branches in this repository, the workflow is skipped to avoid running it twice (once for the
-#   push and once for the PR).
-# - The full workflow (including jobs requiring secrets) runs only on pushes events to branches in this repository
-on: [ push, pull_request ]
+# - For pull requests from forks (coming from a different repository), we still run the full
+#   build/test/lint matrix — none of those steps need secrets.
+# - For pull requests from branches in this repository, the workflow is skipped to avoid running
+#   it twice (once for the push and once for the PR).
+# - npm publish + Anthropic registration run only on semantic version tags (vX.Y.Z) pushed to
+#   this repository.
+on: [push, pull_request]
 concurrency: ci-${{ github.ref }}
 
 permissions:
   contents: read
-  checks: write
 
 jobs:
   build:
     name: Build, test and package
-    # run this job only for push (avoiding pull requests from the same repo) or for pull requests from different repo
+    # run this job only for push (avoiding pull requests from the same repo) or for pull requests from a different repo
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        node-version: ['22', '24']
     outputs:
       is_semantic_tag: ${{ steps.get_package_version.outputs.is_semantic_tag }}
       tag: ${{ steps.get_package_version.outputs.tag }}
       version: ${{ steps.get_package_version.outputs.version }}
-      wheel_artifact_id: ${{ steps.wheel_artifact_upload.outputs.artifact-id }}
     steps:
       - uses: actions/checkout@v6
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      - name: Set up Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
         with:
-          python-version: ${{ matrix.python-version }}
+          node-version: ${{ matrix.node-version }}
+          cache: npm
 
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install uv
-          uv sync --frozen --no-editable --extra dev
-
-      # Runs tests with coverage and generates coverage.xml file and test-results.xml file
-      # and checks flake8 code-style formatting that is compatible with isort & black
-      # and verifies TOOLS.md is up-to-date with tool definitions
-      # see setup in pyproject.toml
-      - name: Unit tests, code style and documentation check
-        run: |
-          uv run tox
-
-      - name: Publish test results
-        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2  # v3.0.0
-        # don't fail the job if the Checks API call flakes — the tests themselves already ran
-        continue-on-error: true
-        # run this step even if a previous step failed, but only for push events or pull requests from the same repo
-        if: (success() || failure()) && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository)
-        with:
-          name: Test results (${{ matrix.python-version }})
-          path: ./test-results.xml
-          reporter: 'java-junit'
-
-      - name: Upload coverage to Codecov
-        # run this step only for push events or pull requests from the same repo
-        if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
-        uses: codecov/codecov-action@v7.0.0
-        with:
-          file: ./coverage.xml
-          fail_ci_if_error: false  # Codecov upload is best-effort — transient service outages should not block CI
-          token: ${{ secrets.CODECOV_TOKEN }}
+        run: npm ci
 
-      - name: Build wheels package
-        run: |
-          uv build --wheel --no-sources
+      - name: Type-check
+        run: npm run type-check
+
+      - name: Lint and format check
+        run: npm run lint
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Verify TOOLS.md is up to date
+        run: npm run check:tools-docs
+
+      - name: Build package
+        run: npm run build
+        env:
+          SKIP_ENV_VALIDATION: '1'
 
       - name: Get package version
         id: get_package_version
-        if: matrix.python-version == '3.10'
+        if: matrix.node-version == '22'
         run: |
-          VERSION=`uv run python3 -c 'import importlib.metadata; print(importlib.metadata.version("keboola_mcp_server"))'`
+          VERSION=$(node -p "require('./package.json').version")
           TAG="${GITHUB_REF##*/}"
           IS_SEMANTIC_TAG=$(echo "$TAG" | grep -q '^v\?[0-9]\+\.[0-9]\+\.[0-9]\+$' && echo true || echo false)
           echo "Version = '$VERSION', Tag = '$TAG', is semantic tag = '$IS_SEMANTIC_TAG'"
-          echo "is_semantic_tag=$IS_SEMANTIC_TAG" >> $GITHUB_OUTPUT
-          echo "tag=$TAG" >> $GITHUB_OUTPUT
-          echo "version=${VERSION}" >> $GITHUB_OUTPUT
-
-      - name: Upload wheel package
-        id: wheel_artifact_upload
-        # run this step only for push events or pull requests from the same repo
-        if: matrix.python-version == '3.10' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository)
-        uses: actions/upload-artifact@v7
-        with:
-          name: keboola_mcp_server-${{ steps.get_package_version.outputs.version }}-py3-none-any.whl
-          path: dist/keboola_mcp_server-${{ steps.get_package_version.outputs.version }}-py3-none-any.whl
-          if-no-files-found: error
-          compression-level: 0  # wheels are ZIP archives
-          retention-days: 7
+          echo "is_semantic_tag=$IS_SEMANTIC_TAG" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
 
   integration_tests:
-    name: Integration Tests
-    needs: build
-    # run this job only for push events (not pull requests)
+    name: Integration tests
+    # Runs in parallel with `build` (independent job) so the fast unit lane isn't blocked.
+    # Push-only: PRs from forks have no access to the project-pool secrets.
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
-      # This ensures tests run sequentially, not in parallel
-      max-parallel: 1
     steps:
       - uses: actions/checkout@v6
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      - name: Set up Node
+        uses: actions/setup-node@v4
         with:
-          python-version: ${{ matrix.python-version }}
+          node-version: '22'
+          cache: npm
 
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install uv
-          uv sync --frozen --no-editable --extra dev
+        run: npm ci
 
-      - name: Integration tests
-        # run actual tests only for pushes to the same repository (not forks)
-        if: github.repository == github.event.repository.full_name
-        env:
-          INTEGTEST_STORAGE_TOKENS: ${{ secrets.INTEGTEST_STORAGE_TOKENS }}
-          INTEGTEST_POOL_STORAGE_API_URL: ${{ vars.INTEGTEST_POOL_STORAGE_API_URL }}
-          INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES: ${{ secrets.INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES }}
-        run: |
-          uv run tox -e integtests
-
-      - name: Skip integration tests for forks
-        # show a message when tests are skipped for forks
-        if: github.repository != github.event.repository.full_name
-        run: |
-          echo "Integration tests skipped for fork repository"
-          echo "Dependencies installed successfully - setup is working correctly"
-
-      - name: Publish integration test results
-        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2  # v3.0.0
-        # don't fail the job if the Checks API call flakes — the tests themselves already ran
-        continue-on-error: true
-        # publish results only when actual tests were run (same repository)
-        if: (always()) && github.repository == github.event.repository.full_name
+      # Unwrap the project pool: substitute $TEST_KBC_PROJECT_*_TOKEN secrets into
+      # .github/ci/projects.json -> ./projects.json (mirrors keboola/go-monorepo).
+      - name: Export Keboola test projects
+        id: projects
+        uses: ./.github/actions/export-kbc-projects
         with:
-          name: Integration test results (${{ matrix.python-version }})
-          path: ./integtest-results.xml
-          reporter: 'java-junit'
+          secrets: ${{ toJSON(secrets) }}
 
-  deploy_to_pypi:
-    name: Deploy to pypi.org
+      - name: Integration tests
+        env:
+          # Cross-runner project lease via the shared redis (same key scheme as go-monorepo,
+          # so leases coordinate with other consumers of the pool).
+          TEST_MCP_PROJECTS_LOCK_HOST: ${{ vars.TEST_MCP_PROJECTS_LOCK_HOST }}
+          TEST_MCP_PROJECTS_LOCK_PASSWORD: ${{ secrets.TEST_MCP_PROJECTS_LOCK_PASSWORD }}
+          TEST_KBC_PROJECTS_FILE: ${{ steps.projects.outputs.projects-file }}
+        run: npm run test:integ
+
+  publish_npm:
+    name: Publish to npm
     needs:
       - build
-      - integration_tests
     runs-on: ubuntu-latest
+    # Publish only on a semantic vX.Y.Z tag that matches package.json's version.
     if: |
       startsWith(github.ref, 'refs/tags/') &&
       needs.build.outputs.is_semantic_tag == 'true' &&
       needs.build.outputs.tag == format('v{0}', needs.build.outputs.version)
+    permissions:
+      contents: read
+      id-token: write # npm provenance
     steps:
-      - name: Download wheel package
-        uses: actions/download-artifact@v8
-        with:
-          name: keboola_mcp_server-${{ needs.build.outputs.version }}-py3-none-any.whl
-          path: dist/
+      - uses: actions/checkout@v6
 
-      - name: Publish package
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+      - name: Set up Node
+        uses: actions/setup-node@v4
         with:
-          user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          node-version: '22'
+          cache: npm
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+        env:
+          SKIP_ENV_VALIDATION: '1'
+
+      - name: Publish
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   register-with-anthropic:
     name: Register with Anthropic
     needs:
       - build
-      - deploy_to_pypi
+      - publish_npm
     runs-on: ubuntu-latest
     if: |
       startsWith(github.ref, 'refs/tags/') &&