osls 4 migration for 2.0.1 (ADR-050) #665

This issue is the execution plan for ADR-050: Move to osls 4 for 2.0.1 (#664). It replaces the "stay on osls 3" position in #639. Line numbers are on next @ 747a479f. All paths are under packages/devtools/infrastructure/ unless noted.

The work ships in two PRs, so that each artifact diff isolates one change:

• PR 1 converts the config while Frigg is still on osls 3.
• PR 2 bumps osls to 4.

2.0.1 does not ship until every box is checked.

PR 1 — conversion, still on osls 3.78.0

Helper

• Add domains/shared/utilities/package-patterns.js → toPackagePatterns({ include, exclude }) returning [!exclude…, include…] (an exclude that already starts with ! becomes an include in exclude position, as osls 3 handles it)
• Unit tests: ordering, a !-prefixed exclude, an include re-adding an excluded path, empty lists, nestedNodeModulesExcludes() output for both keepNestedNodeModules modes

Convert each emitter to package.patterns

• E1 domains/shared/utilities/base-definition-factory.js:41 skipEsbuildPackageConfig (include :43, exclude :49) → auth :288, user :304, health :311
• E2 base-definition-factory.js:117 functionPackageConfig: delete (unused)
• E3 domains/integration/integration-builder.js:254 createFunctionPackageConfig (exclude :257) → <name>Webhook :346, <name> :373, extension routes :419, <name>QueueWorker :439, dlqProcessor :544
• E4 domains/database/migration-builder.js:243 worker config (exclude :245; keep individually) → dbMigrationWorker :437
• E5 migration-builder.js:333 router config (exclude :335; keep individually) → dbMigrationRouter :463
• E6 domains/admin-scripts/admin-script-builder.js:393 skipEsbuildPackageConfig() (include :396, exclude :400) → adminScriptExecutor :195, adminScriptRouter :215, reportRouter :249, reportExecutor :316
• Leave custom.esbuild.exclude (base-definition-factory.js:253, esbuild.config.js:46) unchanged; it is a serverless-esbuild option, not osls packaging

useDotenv

• U1 base-definition-factory.js:176 → ...(process.argv.includes('offline') && { useDotenv: true })
• Test: absent for build/deploy argv, true for offline

Tests

• Update assertions in base-definition-factory.test.js, integration-builder.test.js, migration-builder.test.js and admin-script-builder.test.js (they assert on .include/.exclude today)
• Composer-level test: compose a fully featured definition (VPC, KMS, an integration with a webhook, a queue worker, an extension, migrations, admin scripts). Assert that no function has package.include/package.exclude, and that useDotenv is never false
• Extend the scaffold default-infrastructure test from fix: lazy-load scheduler AWS SDK in core and repair frigg init scaffolding #639, if it has merged, with the same assertions

Cleanup

• packages/serverless-plugin/index.js: delete the dead asyncInit / setupOfflineQueues / createLocalStackSQSClient path. Its require('aws-sdk') (:103) is undeclared and resolves only through osls 3's SDK v2

Artifact gate 1 (expected: identical)

• Run frigg build --stage prod on osls 3.78.0, before and after PR 1, for (a) the scaffold and (b) a featured app (integration + webhook + queue worker + migrations + admin scripts)
• For each zip in .serverless/, diff the sorted unzip -Z1 and the per-file CRC from unzip -lv. Attach the results to the PR

PR 2 — bump to osls 4.4.0

• Change osls to ^4.4.0 in packages/devtools/package.json (devDependency) and packages/devtools/frigg-cli/package.json (dependency); regenerate the lockfile
• Use a single frameworkVersion constant '^4.4.0', replacing base-definition-factory.js:169 ('>=3.17.0') and domains/shared/utilities/logging-config.js:10 ('>=3.58.0'); update the tests
• Set engines.node to ^22.13.0 || >=24 on devtools and frigg-cli; the CLI prints a clear message when the Node version is unsupported
• Leave provider.iamRoleStatements (deprecated in osls 4, warning only). Open a follow-up issue for provider.iam.role.statements before osls 5
• Validate the composed definitions for (a) and (b) against the osls 4.4.0 schema with configValidationMode: error

Artifact gate 2 (osls 3.78.0 vs 4.4.0, both converted)

• Per-function file-list and CRC diff for (a) and (b); every difference is explained in the PR
• Diff cloudformation-template-update-stack.json after normalising artifact hashes
• Record zipped and unzipped size per function for v3 and v4 (the scratch run measured about 73 MB zipped per function with no baseline); every function stays under Lambda's 250 MB unzipped limit

Runtime checks

• frigg start on (a) and (b): GET /health 200, user create and login, integration list, one SQS message processed via serverless-offline-sqs
• frigg build --stage prod against moto (AWS_ENDPOINT_URL) and against real credentials
• Sandbox deploy of (b): frigg deploy --stage <sandbox>. Invoke health, auth, an integration route, a webhook, a queue worker, dlqProcessor (send a poison message), the migration router and worker, and an admin script. Then redeploy with no changes and confirm that no functions are updated
• frigg doctor <stack> on the sandbox stack is healthy, with no drift

Docs

• docs/reference/aws-sdk-v3-osls-migration.md: replace the fix: lazy-load scheduler AWS SDK in core and repair frigg init scaffolding #639 "Why osls 3 and not osls 4" section with osls 4 instructions and a link to ADR-050
• Write an "Upgrading to 2.0.1" note covering these customisations and their fixes:
  • package.include/exclude → patterns
  • useDotenv: false → remove the key
  • frameworkVersion: '3' → ^4.4.0
  • Service-level package.patterns now apply before function excludes
  • Plugins that use SDK v2 surfaces (osls-aws-provider-request-shim)
  • Node 23 is unsupported
• Operator notes:
  • Credential resolution: static keys plus role_arn in the same profile now assume the role; mfa_serial prompts and fails in CI
  • Regional STS endpoints
  • A leftover AWS_ENDPOINT_URL redirects real deploys
  • CRC32 S3 checksums (AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED for S3-compatible targets)
• Update the frigg skill and any doc that references osls ^3.x
• Update website/roadmap/data/adrs.json and the ADR-050 status to Implemented in PR 2 (per ADR-043)

Rollback

PR 1 is valid on osls 3, so rolling back means reverting PR 2 only. After release, 2.0.2 restores osls ^3.78.0 and a frameworkVersion range that accepts 3.x.

Refs: #664 (ADR-050), #639, #646 (ADR-043)