Repository navigation
docs(adr): ADR-050 — move to osls 4 for 2.0.1 - #664
seanspeaks wants to merge 1 commit into
Conversation
Records the decision to target osls ^4.4.0 in 2.0.1: convert every function-level package.include/exclude to order-preserving package.patterns (with an equivalence argument against the osls 3 and 4 packaging code), emit useDotenv only when true, pin frameworkVersion, tighten engines to Node ^22.13.0 || >=24, plus a plugin compatibility matrix, artifact-diff verification plan and rollback. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
seanspeaks
added
release
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.
Once extra usage is available, comment @claude review on this pull request, or push a new commit, to trigger a review.
✅ Deploy Preview for friggframework-org ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Execution plan / tracking issue: #665 |
|
|
ADR reconciliation needed after Stack A/B — drafted with Claude Code at Sean's request Severity: cross-ref only.
|
Frigg 2.0.1 ADR review (COMMENT only — not an approval / not changes-requested)Verdict: changes needed (would not approve until corrected) Blocking
Otherwiseosls 4 migration guidance (patterns helper, Would approve after: the asyncInit / SDK v3 correction is written into the ADR (and the “Delete it” guidance is removed). |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| | `serverless-offline` | 13.10.1 | always (used by `frigg start`) | Compatible. CLI options are typed. No removed surfaces. Its `peerDependencies: serverless ^3.2.0` makes npm install upstream `serverless@3.40.0` beside osls. This is unchanged and harmless, because Frigg spawns `osls` by name. | | ||
| | `serverless-offline-sqs` | 8.0.0 | always | Compatible. It uses `aws-sdk/clients/sqs` (v2), which it declares as its **own** dependency, not through osls. | | ||
| | `serverless-dotenv-plugin` | 6.0.0 | `offline` only | Compatible. No removed surfaces. | | ||
| | `@friggframework/serverless-plugin` | workspace | always | Compatible in the paths it runs. `asyncInit()` → `createLocalStackSQSClient()` (`index.js:103`) calls `require('aws-sdk')`, which is **undeclared** and resolves today only because osls 3 hoists SDK v2. That method is not attached to any hook, so it is dead code. Delete it in the migration, so that a later change cannot attach a hook that breaks on osls 4. | |
There was a problem hiding this comment.
[blocking] asyncInit is not dead code — do not delete it.
This row says asyncInit() → createLocalStackSQSClient() “is not attached to any hook, so it is dead code. Delete it in the migration.” That is incorrect.
osls calls plugin.asyncInit() from PluginManager.loadAllPlugins → asyncPluginInit() on every plugin load (osls 3.78 and 4.4). On frigg start this path creates the LocalStack queues. Deleting it breaks offline queue provisioning.
Required correction (already recorded as a deviation on implementation PR #704): keep asyncInit / setupOfflineQueues, and migrate createLocalStackSQSClient to a declared AWS SDK v3 @aws-sdk/client-sqs client (undeclared aws-sdk v2 was only resolving via osls 3 hoist).
Failure scenario: an implementer follows this ADR literally, deletes asyncInit, and frigg start no longer creates InternalErrorQueue / DemoQueue / AdminScriptQueue (or equivalent app queues).
seanspeaks
left a comment
seanspeaks
left a comment
There was a problem hiding this comment.
Frigg 2.0.1 review: verified findings below against this head and its actual base/current next. This review comment does not constitute release approval; broader stack and test verification is still in progress.
| | `serverless-offline` | 13.10.1 | always (used by `frigg start`) | Compatible. CLI options are typed. No removed surfaces. Its `peerDependencies: serverless ^3.2.0` makes npm install upstream `serverless@3.40.0` beside osls. This is unchanged and harmless, because Frigg spawns `osls` by name. | | ||
| | `serverless-offline-sqs` | 8.0.0 | always | Compatible. It uses `aws-sdk/clients/sqs` (v2), which it declares as its **own** dependency, not through osls. | | ||
| | `serverless-dotenv-plugin` | 6.0.0 | `offline` only | Compatible. No removed surfaces. | | ||
| | `@friggframework/serverless-plugin` | workspace | always | Compatible in the paths it runs. `asyncInit()` → `createLocalStackSQSClient()` (`index.js:103`) calls `require('aws-sdk')`, which is **undeclared** and resolves today only because osls 3 hoists SDK v2. That method is not attached to any hook, so it is dead code. Delete it in the migration, so that a later change cannot attach a hook that breaks on osls 4. | |
There was a problem hiding this comment.
[P2 / should-fix] Correct the instruction to delete a live plugin initializer
asyncInit() is invoked directly by osls during plugin loading, even without a registered hook. On a fresh LocalStack, deleting it as this row instructs means frigg start no longer creates the integration queues. The implementation in #704 correctly preserves this path and replaces its client with AWS SDK v3. Please record that correction here and remove the dead-code/deletion requirement. Evidence: osls v4.4.0 plugin loader and preserved initializer in #704.
Summary
Adds ADR-050: Move to osls 4 for 2.0.1 (Status: Accepted). The maintainer made the decision, and under ADR-043 (#646) merging the ADR is its acceptance.
osls ^4.4.0. osls 3 is now thelegacydist-tag and pulls AWS SDK v2 into every app. 2.0.1 is the cheapest point in the 2.x line to make this change.package.include/package.exclude. The ADR lists every emitter with file:line: the core functions, integration HTTP, webhook, extension, queue-worker and DLQ functions, migrations and admin scripts. One emitter (base-definition-factory.js:117) is dead code.useDotenv: false.toPackagePatterns({ include, exclude })helper emits[!exclude…, include…]. The ADR argues from the osls 3.78.0 and 4.4.0package-service.jsandutils/glob.jscode that this gives the same file set.useDotenvbecomes "trueor absent". Both changes are valid on osls 3, so they land and are verified before the pin bump.frameworkVersion: '^4.4.0'from one constant, so a mismatch fails fast.engines.node^22.13.0 || >=24, because Node 23 and 22.0–22.12 are unsupported by both osls majors.provider.iamRoleStatementsis kept for now. In v4 it is only a warning, and renaming it would break app wrappers.@friggframework/serverless-pluginhas an unreachable, undeclaredrequire('aws-sdk'), which the migration deletes.frigg start,frigg build, a real sandbox deploy, andfrigg doctor.Also adds the README index row and the
website/roadmap/data/adrs.jsonentry.Supersedes the "Why osls 3 and not osls 4" section added in #639. The execution plan is in the tracking issue (linked in a comment).
Test plan
next🤖 Generated with Claude Code
📦 Published PR as canary version:
2.0.0--canary.664.a0b36e4.0✨ Test out this PR locally via:
npm install @friggframework/admin-scripts@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/core@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/devtools@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/eslint-config@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/prettier-config@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/schemas@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/serverless-plugin@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/test@2.0.0--canary.664.a0b36e4.0 npm install @friggframework/ui@2.0.0--canary.664.a0b36e4.0 # or yarn add @friggframework/admin-scripts@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/core@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/devtools@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/eslint-config@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/prettier-config@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/schemas@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/serverless-plugin@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/test@2.0.0--canary.664.a0b36e4.0 yarn add @friggframework/ui@2.0.0--canary.664.a0b36e4.0