Repository navigation
feat(devtools)!: move to osls 4 for 2.0.1 (ADR-050) - #704
Open
seanspeaks wants to merge 5 commits into
Open
seanspeaks wants to merge 5 commits into
seanspeaks wants to merge 5 commits into
Conversation
seanspeaks
added
release
✅ Deploy Preview for friggframework-org canceled.
|
seanspeaks
marked this pull request as ready for review
October 22, 2026 20:56
![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, someone with write access to this repository can comment @claude review on this pull request to trigger a review.
osls 4 rejects function-level package.include / package.exclude and
accepts only `useDotenv: true`. Convert every emitter while Frigg is
still on osls 3, where package.patterns is equally valid, so the change
can be verified on its own.
- Add toPackagePatterns({ include, exclude }) -> [!exclude..., include...].
osls 3 placed a function's excludes (negated) ahead of its includes in
resolveFilePathsFromPatterns, and Frigg emits no service-level
include/exclude/patterns, so this is the same ordered list. An exclude
that already starts with `!` becomes an include in exclude position,
as osls 3 handled it.
- Route the auth/user/health config (base-definition-factory), the
integration function config, both migration configs and the admin
script/report config through the helper. The lists are unchanged.
- Delete the unused functionPackageConfig in base-definition-factory.
- Emit `useDotenv: true` only for `offline`; omit the key otherwise
(osls treats an absent key as false).
- custom.esbuild.exclude is a serverless-esbuild option and is unchanged.
Tests: helper table tests against the osls 3 ordering, per-builder
assertions that no function carries include/exclude, and a composer
test that walks every function of a fully featured definition.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
…v3 client createLocalStackSQSClient() required 'aws-sdk', which the plugin never declared; it resolved only because osls 3 depends on SDK v2. ADR-050 treats this path as dead code, but osls calls asyncInit() on every plugin in PluginManager.loadAllPlugins (osls 3 and 4), so it runs on every `frigg start` to create the LocalStack queues. Deleting it would break offline queues. Keep the path and build the client from @aws-sdk/client-sqs (now a declared dependency). The v3 aggregated SQS client keeps the callback-style createQueue that LocalStackQueueService calls, with the same region, endpoint and LocalStack credential defaults. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
- osls ^4.4.0 in devtools (devDependency) and frigg-cli (dependency);
lockfile regenerated. osls 4 drops the AWS SDK v2 dependency that
osls 3 brought into every app.
- One OSLS_FRAMEWORK_VERSION constant ('^4.4.0') replaces '>=3.17.0' in
base-definition-factory and the ADR-048 LoggingConfig floor
('>=3.58.0') in logging-config. An app that still resolves osls 3 now
fails fast with FRAMEWORK_VERSION_MISMATCH.
- engines.node '^22.13.0 || >=24' on devtools and frigg-cli. The CLI
checks the host Node version first and prints a clear message on
Node 23 and Node 22.0-22.12 (FRIGG_SKIP_NODE_VERSION_CHECK=true
bypasses it).
- serverless-config schema accepts caret/tilde ranges; management-ui
scaffold and schema examples use '^4.4.0'.
- provider.iamRoleStatements is unchanged (osls 4 deprecation warning
only; tracked for osls 5).
BREAKING CHANGE: apps must run osls 4. Apps whose infrastructure.js adds
package.include/exclude, sets useDotenv: false, pins frameworkVersion
'3' or ^3.x, or loads a plugin that uses SDK v2 provider surfaces now
fail. Node 23 and Node 22.0-22.12 hosts are unsupported.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
…DR-050) - aws-sdk-v3-osls-migration.md: osls ^4.4.0 install, the Node host range, what Frigg now emits, an "Upgrading an app to 2.0.1" table (include/exclude -> patterns, useDotenv, frameworkVersion, service patterns ordering, SDK v2 plugin surfaces, Node 23), operator notes (profiles + role_arn, mfa_serial, regional STS, AWS_ENDPOINT_URL, CRC32 checksums), the measured per-function sizes and budget, and rollback. - devtools, infrastructure and frigg-cli READMEs: requirements and the packaging rules; LOGGING.md and the frigg skill reference updated. - frigg-cli dependency test now requires osls 4.4+ within major 4. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
#639 added the SDK v3 LocalStack client and its tests with @aws-sdk/client-sqs mocked; the ADR-050 copies needed the real client and failed under that mock. Keep only the guard that the plugin no longer requires aws-sdk. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
seanspeaks
force-pushed
the
feat/osls-4
branch
from
October 23, 2026 16:06
79d9a63 to
6a606c3
Compare
|
2 tasks
Frigg 2.0.1 review (Group 2) — COMMENT onlyChecklist
Verdict (would): would approve Findings
No blocking issues for ADR-050. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| */ | ||
| function toPackagePatterns({ include = [], exclude = [] } = {}) { | ||
| return [ | ||
| ...exclude.map((pattern) => |
There was a problem hiding this comment.
Checklist note (pass): toPackagePatterns emits excludes (negated) before includes, matching osls 3’s include/exclude evaluation order for osls 4 package.patterns.
Follow-up findings (COMMENT)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements ADR-050 (#664): Frigg 2.0.1 moves from osls 3 to osls
^4.4.0. Execution checklist: #665. The PR has two code steps so each artifact diff isolates one change: commit 1 converts the config while on osls 3, and commit 3 bumps osls.feat(devtools): emit package.patterns and omit useDotenv=falsetoPackagePatterns({ include, exclude })→[!exclude…, include…]. Routes E1 (auth/user/health), E3 (integration HTTP, webhook, extension routes, queue worker,dlqProcessor), E4/E5 (migration worker/router,individuallykept) and E6 (admin script + report functions) through it. Deletes the dead E2functionPackageConfig. EmitsuseDotenv: trueonly foroffline. Leavescustom.esbuild.excludealone.fix(serverless-plugin): create LocalStack queues with a declared SDK v3 clientfeat(devtools)!: move to osls ^4.4.0 with one frameworkVersionosls ^4.4.0(devtools devDep, frigg-cli dep, lockfile). A singleOSLS_FRAMEWORK_VERSION = '^4.4.0'replaces>=3.17.0and the ADR-048>=3.58.0floor.engines.node: ^22.13.0 || >=24on devtools and frigg-cli. The CLI checks the Node version first and prints a clear message. The serverless-config schema accepts^/~ranges. The management-ui scaffold uses^4.4.0.iamRoleStatementsis unchanged.docs: osls 4 upgrade notes, operator notes and package size budgetdocs/reference/aws-sdk-v3-osls-migration.md, the devtools, infrastructure and frigg-cli READMEs,LOGGING.md, and thefriggskill reference.Deviation from ADR-050:
asyncInitin serverless-plugin is not dead codeADR-050 says
asyncInit→setupOfflineQueues→createLocalStackSQSClient(require('aws-sdk')) is not attached to a hook and can be deleted. That is not right. osls callsplugin.asyncInit()on every plugin inPluginManager.loadAllPlugins→asyncPluginInit(). This happens in osls 3.78.0 (plugin-manager.js:147/677) and in osls 4.4.0 (:208/753). So this path creates the LocalStack queues on everyfrigg start, and deleting it would break offline queues.I kept the path and changed the client to a declared
@aws-sdk/client-sqsv3 aggregatedSQSclient, which keeps the callback-stylecreateQueue. I verified it under osls 4:frigg starton the featured app createdInternalErrorQueue,DemoQueueandAdminScriptQueueon a moto endpoint at:4566and set the*_QUEUE_URLenv vars. I suggest an ADR-050 erratum.Equivalence check (pattern ordering)
I read
resolveFilePathsFromPatternsin both versions (osls 3.78.0package-service.js:262, osls 4.4.0:253). Frigg emits no service-level include, exclude or patterns. Functionpatternsgo in include position unchanged. So[!exclude…, include…]gives exactly the osls 3 list:[!defaults…, !funcExclude…, funcInclude…, devDepIncludes…, !devDepExcludes…].lib/utils/glob.jsis byte-identical in the two versions, and so isexcludeDevDependencies. InbuildTasks, a!xpattern only prunes the**candidates that come before it. A file pruned that way would also be set to excluded by!xin the osls 3 list. Later positive patterns (the CA file, dev-dep re-includes) are globbed as their own tasks. The artifact diffs below confirm the result.Artifact gate 1: conversion only, osls 3.78.0 both sides
Two apps, packaged with
osls package --config infrastructure.js --stage prod(whatfrigg build --productionruns). Discovery and the layerdescribeStacksran against moto (AWS_ENDPOINT_URL, plus a preload that points osls 3's SDK v2 at moto). No real AWS.auth,user,health,dbMigrationRouter,dbMigrationWorker,prismalayerdemo+demoWebhook+demoQueueWorker,dlqProcessor,dbMigrationRouter/Worker,adminScriptExecutor/Router, VPC on,prismalayerfrigg initis not usable onnext(thefrigg-cli/templatesdir is missing), so I hand-built both apps.unzip -Z1, sorted)unzip -lv).frigg-infrastructure-cache.json.frigg-infrastructure-cache.jsonLambdaVersion<hash>/CodeSha256and layer hashes, with sorted keys..frigg-infrastructure-cache.jsonis the composed-definition cache. It holds a timestamp and the definition, so it changes on every build. Code hashes differ only because of it. Pre-existing: this file is shipped in every function zip. That is worth a follow-up that excludes it.useDotenv: must be equal to constantand the include/exclude deprecation are gone.Artifact gate 2: osls 3.78.0 (converted) vs osls 4.4.0
package.json,node_modules/.package-lock.jsonand the cache filepackage.jsonis the app's own file; itsoslsdevDependency changed.node_modules/.package-lock.jsonis npm's hidden lockfile.configValidationMode: error, with no config errors. The only remaining deprecation is the expectediamRoleStatementsone.Sizes
Identical on v3 and v4.
dlqProcessor, admin functionsdbMigrationRouterdbMigrationWorkerprismalayer***innpm ls --parseableoutput. osls's dev-dependency exclusion parses that output. In a project path that contains a UUID, the exclusion matches nothing and every function ships the dev tree: about 195 MB unzipped and 67.6 MB zipped here, before I worked around it. This is independent of osls 3 vs 4, and it probably explains the ~73 MB zips in ADR-050's scratch run. All numbers above come from a run with a test-harnessnpmshim that un-masks the path. The doc tells users to build from a path without a UUID.Runtime checks
frigg start, Node 24.10.0, osls 4.4.0:GET /health→ 200GET /health→ 200, and the three LocalStack queues were created through the new SDK v3 clientFRIGG_SKIP_NODE_VERSION_CHECK=true, osls itself refuses:osls v4.4.0 does not support Node.js v23.5.0 … Supported versions: ^20.19.0 || ^22.13.0 || >=24.Tests
Baseline is
origin/nextvs this branch, Node 24, same install.infrastructure/**next, with the same or fewer failures.infrastructure-composer.test.js(51),template-generation.test.js,cloudformation-discovery.test.js,vpc-builder.test.js(8), health-domain suites,postgres-config,integration.test.js,build-time-discovery,build-prisma-layer,aws-provider-adapter, and the helper/fixture files picked up as suites.template-generation: went from 29 to 20 failures. That is environmental (Prisma layer build state), not from this change.install.test.js(3),dependencies.test.js(1: expects devtools as a dependency),doctor/deploy/generatesuite-load errors.nestedNodeModulesExcludesin both modesuseDotenvargv test#665 checklist (items completed here)
PR 1 / helper and conversion:
toPackagePatternshelper + unit tests (ordering,!-prefixed exclude, re-include, empty lists,nestedNodeModulesExcludesboth modes)custom.esbuild.excludeunchangeduseDotenvemitted only when true + argv testExtend the scaffold default-infrastructure test from fix: lazy-load scheduler AWS SDK in core and repair: fix: lazy-load scheduler AWS SDK in core and repairfrigg initscaffolding #639frigg initscaffolding #639 is not mergedPR 2 / bump:
^4.4.0in devtools + frigg-cli, lockfile regeneratedframeworkVersionconstant^4.4.0, tests updatedengines.node^22.13.0 || >=24; the CLI prints a clear messageiamRoleStatementsleft as isprovider.iam.role.statements(not opened from here)configValidationMode: error(packaged with no config errors)Runtime:
frigg startGET /health200 on (a) and (b) (partial: user/login, integration list and the SQS message were not run)frigg build --stage prodagainst motofrigg buildagainst real credentialsfrigg doctoron the sandbox stackDocs:
aws-sdk-v3-osls-migration.mdupdated for osls 4 (the fix: lazy-load scheduler AWS SDK in core and repairfrigg initscaffolding #639 section never landed onnext, so there was nothing to replace)friggskill and docs that reference osls 3 updated (docs/reference/deployment-fixes.mdis left as a historical record)website/roadmap/data/adrs.json: ADR-050 is not onnextyet (docs(adr): ADR-050 — move to osls 4 for 2.0.1 #664)Other findings (not fixed here)
@friggframework/core@2.0.0-next.120requires@aws-sdk/client-schedulerwithout declaring it. The chain isinfrastructure/scheduler/eventbridge-scheduler-adapter.jsviacore/index.js, and onlypackages/admin-scriptsdeclares the package. An app that installs only core plus devtools fails to loadinfrastructure.js. I added the package to the test apps to get past it..frigg-infrastructure-cache.jsonis packaged into every function zip. It holds the full composed definition.Test plan
npx jest infrastructure(devtools), serverless-plugin, frigg-cli and schemas suites: compared abovefrigg starton Node 24 (GET /health200); Node 23 behaviour checked🤖 Generated with Claude Code
https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
📦 Published PR as canary version:
2.0.0--canary.704.6a606c3.0✨ Test out this PR locally via:
npm install @friggframework/admin-scripts@2.0.0--canary.704.6a606c3.0 npm install @friggframework/core@2.0.0--canary.704.6a606c3.0 npm install @friggframework/devtools@2.0.0--canary.704.6a606c3.0 npm install @friggframework/eslint-config@2.0.0--canary.704.6a606c3.0 npm install @friggframework/prettier-config@2.0.0--canary.704.6a606c3.0 npm install @friggframework/schemas@2.0.0--canary.704.6a606c3.0 npm install @friggframework/serverless-plugin@2.0.0--canary.704.6a606c3.0 npm install @friggframework/test@2.0.0--canary.704.6a606c3.0 npm install @friggframework/ui@2.0.0--canary.704.6a606c3.0 # or yarn add @friggframework/admin-scripts@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/core@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/devtools@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/eslint-config@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/prettier-config@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/schemas@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/serverless-plugin@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/test@2.0.0--canary.704.6a606c3.0 yarn add @friggframework/ui@2.0.0--canary.704.6a606c3.0Note
High Risk
Changes the deploy toolchain, Lambda packaging contract, and supported Node versions; misconfigured apps or leftover osls 3 pins can fail builds or ship oversized bundles, and osls 4 credential/
AWS_ENDPOINT_URLbehavior can misroute deploys.Overview
Frigg 2.0.1 targets osls
^4.4.0(ADR-050): devtools and frigg-cli bump the dependency and lockfile, and composed definitions emit a singleframeworkVersion: ^4.4.0viaOSLS_FRAMEWORK_VERSIONinstead of osls 3 ranges.Infrastructure builders now ship Lambda packaging as
package.patternsthroughtoPackagePatterns(excludes negated first, then includes), withuseDotenv: trueonly forfrigg start/ offline. The CLI enforces host Node^22.13.0 || >=24before startup (FRIGG_SKIP_NODE_VERSION_CHECKto bypass). Tests and docs cover upgrade rules, operator/credential notes, and package size budgets; scaffold/schema examples move to^4.4.0.Reviewed by Cursor Bugbot for commit 6a606c3. Bugbot is set up for automated code reviews on this repo. Configure here.