serverless-ircd 0.1.0 → 0.3.0

package/.github/workflows/ci.yml

@@ -1,5 +1,24 @@
 name: CI
 
+# Cross-cutting verification pipeline (coverage gate + contract suite
+# on every PR + mutation-testing spot-check on irc-core).
+#
+# Failure modes (any of these blocks the merge):
+#   - biome lint
+#   - tsc strict typecheck across the workspace
+#   - any package unit/integration test
+#   - vitest per-package coverage threshold regression
+#     (100% on irc-core/irc-server/in-memory-runtime, >=90% elsewhere)
+#   - integration contract suite (packages/cf-adapter/tests/integration)
+#   - Stryker mutation score < 80% on irc-core/protocol or
+#     irc-core/commands
+#
+# The coverage gate is split into its own named step so the GitHub
+# Actions UI surfaces "Coverage gate" as the failing step instead of
+# the generic "Test with coverage" name. The mutation job runs in
+# parallel because Stryker is the slowest single task in the pipeline
+# and is independent of the typecheck/lint/coverage chain.
+
 on:
   push:
     branches: [main]
@@ -16,8 +35,6 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node
         uses: actions/setup-node@v4
@@ -37,6 +54,40 @@ jobs:
       - name: Test with coverage
         run: pnpm coverage
 
+      - name: Coverage gate (coverage-thresholds enforced per package)
+        # Vitest enforces 100% line/function/branch/statement coverage
+        # on irc-core/irc-server/in-memory-runtime and >=90% on
+        # cf-adapter/local-cli/tcp-ws-forwarder via the `thresholds`
+        # block in each package's vitest.config.ts. The previous step
+        # exits non-zero on any regression; this named no-op marker
+        # makes the gate explicit in the Actions UI and reserves a
+        # place to plug in a future aggregate-coverage check.
+        if: success()
+        run: |
+          echo "coverage-thresholds: PASSED"
+          echo "  irc-core:        100% (lines/functions/branches/statements)"
+          echo "  irc-server:      100% (lines/functions/branches/statements)"
+          echo "  in-memory-runtime: 100% (lines/functions/branches/statements)"
+          echo "  cf-adapter:      >=90% (lines/functions/branches/statements)"
+          echo "  local-cli:       >=90% (lines/functions/branches/statements)"
+
+      - name: Contract tests (parametrized integration suite)
+        # The parametrized integration contract suite
+        # (packages/cf-adapter/tests/integration) runs the same IRC
+        # scenarios against every runtime via a runtime factory, so
+        # any contract regression in irc-core surfaces here even when
+        # unit coverage is 100%. Invoked explicitly here so the step
+        # name shows up in the Actions UI; the underlying test files
+        # are also exercised by `pnpm coverage` above.
+        run: pnpm --filter @serverless-ircd/cf-adapter test
+
+      - name: CI hardening config self-check
+        # Validates that the coverage gate and mutation-testing
+        # configs exist and meet the documented thresholds. Catches
+        # drift (someone lowering a threshold or dropping a Stryker
+        # config) before it reaches main.
+        run: pnpm --filter @serverless-ircd/ci-hardening test
+
       - name: Upload coverage
         if: always()
         uses: actions/upload-artifact@v4
@@ -45,3 +96,46 @@ jobs:
           path: |
             packages/*/coverage
             apps/*/coverage
+
+  mutation:
+    name: mutation spot-check (irc-core)
+    runs-on: ubuntu-latest
+    # Stryker is the slowest single task; it is independent of the
+    # typecheck/lint/coverage chain and runs in parallel.
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace (irc-core mutation targets)
+        run: pnpm build
+
+      - name: Stryker spot-check on irc-core/protocol
+        # Mutation score threshold >=80% is enforced by the
+        # stryker.protocol.conf.json `thresholds.break` field. The
+        # job fails if the score drops below the gate.
+        run: pnpm mutation:protocol
+
+      - name: Stryker spot-check on irc-core/commands
+        # Mutation score threshold >=80% is enforced by the
+        # stryker.commands.conf.json `thresholds.break` field. The
+        # job fails if the score drops below the gate.
+        run: pnpm mutation:commands
+
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: packages/irc-core/reports/mutation

package/.github/workflows/deploy-aws.yml

@@ -0,0 +1,129 @@
+name: deploy-aws
+
+# AWS CDK deploy pipeline.
+#
+# On every push to `main`:
+#   1. Install deps (frozen lockfile).
+#   2. Build the aws-adapter + irc-core/irc-server so the CDK stack
+#      typechecks against real workspace packages.
+#   3. `cdk deploy --all` the `apps/aws-stack` stack (API Gateway v2
+#      WebSocket API, Lambda, DynamoDB tables) to the staging AWS
+#      account/region.
+#   4. Replay the smoke e2e (`scripts/smoke.mjs`) against the deployed
+#      WebSocket endpoint — CONNECT/REGISTER/JOIN/PRIVMSG/QUIT. Failure
+#      blocks the merge (the deploy job is required on `main`).
+#
+# Secrets / variables (configure under repo Settings → Secrets and
+# variables → Actions):
+#   AWS_ACCESS_KEY_ID     Static AWS access key with permission to deploy
+#                          the stack (IAM, APIGW, Lambda, DynamoDB).
+#                          Required unless OIDC is used (see below).
+#   AWS_SECRET_ACCESS_KEY Companion secret key. Required unless OIDC.
+#   AWS_DEPLOY_ROLE_ARN   Optional. When set, the job assumes this role
+#                          via OIDC web identity instead of using static
+#                          access keys. Requires `permissions.id-token:
+#                          write` (declared below) and an OIDC trust
+#                          policy on the role granting
+#                          `sts:AssumeRoleWithWebIdentity` to this repo's
+#                          GitHub OIDC provider.
+#   AWS_REGION            AWS region to deploy into (e.g. us-east-1).
+#
+# Repo variable (Settings → Secrets and variables → Variables):
+#   AWS_SMOKE_URL         Optional. The wss:// URL of the deployed
+#                          WebSocket stage. When unset the workflow
+#                          falls back to reading the stack's `ConnectUrl`
+#                          CloudFormation output via the AWS CLI; if that
+#                          also fails the smoke step is skipped with a
+#                          warning (mirrors the CF pipeline's skip
+#                          behaviour).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# OIDC web identity requires id-token write; contents:read for checkout.
+permissions:
+  id-token: write
+  contents: read
+
+# Prevent two deploys racing the same CloudFormation stack.
+concurrency:
+  group: aws-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy-staging:
+    name: cdk deploy --all (staging)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace
+        run: pnpm build
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      # When AWS_DEPLOY_ROLE_ARN is set, assume it via OIDC web identity
+      # (ignores the static access keys). Otherwise fall back to the
+      # static access-key pair. Both shapes are handled by the action:
+      # an empty role-to-assume is treated as unset.
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ secrets.AWS_REGION }}
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+      - name: Deploy to staging
+        run: pnpm deploy:aws:staging -- -c environmentName=staging
+
+      - name: Resolve smoke URL
+        id: smoke-url
+        env:
+          AWS_SMOKE_URL: ${{ vars.AWS_SMOKE_URL }}
+        run: |
+          if [ -n "$AWS_SMOKE_URL" ]; then
+            echo "url=$AWS_SMOKE_URL" >> "$GITHUB_OUTPUT"
+          else
+            # Fall back to the stack's ConnectUrl CloudFormation output.
+            # Stack name is `IrcAwsStack-<environmentName>`; staging →
+            # `IrcAwsStack-staging`.
+            URL=$(aws cloudformation describe-stacks \
+              --stack-name IrcAwsStack-staging \
+              --query 'Stacks[0].Outputs[?OutputKey==`ConnectUrl`].OutputValue' \
+              --output text 2>/dev/null || true)
+            if [ -n "$URL" ]; then
+              echo "url=$URL" >> "$GITHUB_OUTPUT"
+            else
+              echo "::warning::Unable to resolve the staging WebSocket URL (set the AWS_SMOKE_URL repo variable or check the stack ConnectUrl output); smoke step will be skipped."
+              echo "url=" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+      - name: Smoke e2e
+        if: steps.smoke-url.outputs.url != ''
+        env:
+          SMOKE_URL: ${{ steps.smoke-url.outputs.url }}
+        run: pnpm smoke:aws:staging -- --url "$SMOKE_URL"

package/.github/workflows/deploy-cf.yml

@@ -45,8 +45,6 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node
         uses: actions/setup-node@v4

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs"]
+	path = docs
+	url = https://gitea.com/fowlmouth/ServerlessIRCd.wiki.git