feat require Serverless Framework v4, drop v3 support BREAKING CHANGE: requires Serverless Framework v4; drops v3 support.

Author: sid88in

.github/workflows/ci.yml

@@ -24,6 +24,8 @@ jobs:
         uses: actions/checkout@v6
       - name: Install dependencies
         run: npm ci
+      - name: Verify no deep serverless/lib imports (guards #632)
+        run: npm run verify:imports
       - name: Lint
         run: npm run lint
       - name: Tests
@@ -47,6 +49,13 @@ jobs:
     name: CFN Synthesis Tests
     runs-on: ubuntu-latest
     needs: tests
+    # Serverless Framework v4 requires authentication for every CLI invocation,
+    # including non-interactive CI. The e2e harness spawns `serverless package`,
+    # so a license/access key must be present or the run will fail/prompt.
+    # Add SERVERLESS_ACCESS_KEY (Dashboard > Settings > Access Keys) as a repo
+    # secret. Free for individual developers / orgs under the revenue threshold.
+    env:
+      SERVERLESS_ACCESS_KEY: ${{ secrets.SERVERLESS_ACCESS_KEY }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v6

e2e/README.md

@@ -21,9 +21,15 @@ runs `serverless package` to produce a CloudFormation template, and
 asserts on the generated resources.
 
 Critically, **these tests do not deploy anything to AWS** — they only
-exercise the synthesis path. That makes them fast (~3s per fixture),
-fork-safe (no AWS credentials required), and suitable to run on every
-PR.
+exercise the synthesis path. That makes them fast (~3s per fixture)
+and suitable to run on every PR. No AWS credentials are required.
+
+> **Serverless Framework v4 requires authentication.** As of v4, every
+> CLI invocation (including the `serverless package` these tests run)
+> must be authenticated, even though nothing is deployed. You need a
+> Serverless **Access Key** or **License Key** — free for individual
+> developers and organizations under the revenue threshold. See
+> [Authentication](#authentication-serverless-v4) below.
 
 ## Running locally
 
@@ -38,6 +44,24 @@ npm run test:all
 npx jest --config jest.e2e.config.ts basic-api-key
 ```
 
+### Authentication (Serverless v4)
+
+Set a Serverless Access Key (or License Key) before running, otherwise
+the spawned `serverless package` will fail / prompt for login:
+
+```bash
+# One-time interactive login (writes a key to your machine)
+npx serverless login
+
+# …or set an explicit key for this shell / CI
+export SERVERLESS_ACCESS_KEY=...   # from Dashboard > Settings > Access Keys
+# or
+export SERVERLESS_LICENSE_KEY=...
+```
+
+The harness passes the current environment through to the CLI, so any
+of the above is sufficient.
+
 ## Adding a new test
 
 1. Create a new example under `examples/<feature>/`:
@@ -90,3 +114,7 @@ A dedicated `e2e` job in `.github/workflows/ci.yml` runs the full
 synthesis test suite on every PR and push to `master` or `alpha`. It
 runs after the unit-test matrix completes successfully (no point
 running E2E if unit tests already failed).
+
+The job reads `SERVERLESS_ACCESS_KEY` from repository secrets to
+authenticate the Serverless v4 CLI. Add it under
+**Settings > Secrets and variables > Actions** before this job can pass.

e2e/helpers/synthesize.ts

@@ -93,14 +93,33 @@ export function synthesize(exampleDir: string): SynthesizeResult {
     );
   }
 
-  const templatePath = path.join(
+  // Serverless writes the synthesized template as
+  // `cloudformation-template-update-stack.json`. We look it up defensively
+  // (preferring the canonical name, then falling back to any
+  // `cloudformation-template-*-stack.json`) so the harness is resilient to
+  // any path/name nuance across Serverless Framework major versions.
+  const canonical = path.join(
     packageDir,
     'cloudformation-template-update-stack.json',
   );
+  let templatePath = canonical;
+  if (!fs.existsSync(templatePath)) {
+    const fallback = fs
+      .readdirSync(packageDir)
+      .find(
+        (f) =>
+          /^cloudformation-template-.*-stack\.json$/.test(f) &&
+          f.endsWith('.json'),
+      );
+    if (fallback) {
+      templatePath = path.join(packageDir, fallback);
+    }
+  }
   if (!fs.existsSync(templatePath)) {
     fs.rmSync(packageDir, { recursive: true, force: true });
     throw new Error(
-      `CloudFormation template was not produced at ${templatePath}.`,
+      `CloudFormation template was not produced in ${packageDir} ` +
+        `(expected ${canonical} or a cloudformation-template-*-stack.json).`,
     );
   }