Add npm packaging via sbt-ossuminc and publish to GitHub Packages

respencer-ncl · claude · respencer-ncl · commit c5361e87ec8b · 2026-02-03T23:21:22.000-05:00
Wire up With.Packaging.npm() and With.Publishing.npm() from
sbt-ossuminc 1.2.5-4 for riddlLibJS. Switch Scala.js output from
CommonJS to ESModule to match package.json declaration. Simplify
npm-publish.yml workflow to use sbt tasks instead of custom shell
scripting. Remove misleading export default from TypeScript
declarations.

Published @ossuminc/riddl-lib@1.2.3-1-aef48695-20260203-2217 to
GitHub Packages npm registry.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml
@@ -8,12 +8,11 @@ on:
       registry:
         description: 'Registry to publish to'
         required: true
-        default: 'both'
+        default: 'github'
         type: choice
         options:
-          - npmjs
           - github
-          - both
+          - npmjs
 
 jobs:
   build-and-publish:
@@ -59,146 +58,21 @@ jobs:
         with:
           node-version: '22'
 
-      - name: Build Scala.js
-        run: sbt --batch riddlLibJS/fullLinkJS
-
-      - name: Get version from sbt
-        id: version
-        run: |
-          VERSION=$(sbt --batch "print riddlLibJS/version" 2>/dev/null | grep -v "\[info\]" | grep -v "loading" | tail -1 | tr -d ' ')
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Version: $VERSION"
-
-      - name: Prepare npm package
-        run: |
-          # Find the output directory
-          OUTPUT_DIR=$(find riddlLib/js/target -type d -name "*-opt" | head -1)
-          echo "Output directory: $OUTPUT_DIR"
-
-          # Copy TypeScript definitions
-          cp riddlLib/js/types/index.d.ts "$OUTPUT_DIR/"
-
-          # Create package.json from template with version and TypeScript support
-          cat > "$OUTPUT_DIR/package.json" << EOF
-          {
-            "name": "@ossuminc/riddl-lib",
-            "version": "${{ steps.version.outputs.version }}",
-            "description": "RIDDL Language Library - JavaScript/TypeScript bindings",
-            "main": "main.js",
-            "types": "index.d.ts",
-            "type": "module",
-            "exports": {
-              ".": {
-                "types": "./index.d.ts",
-                "import": "./main.js"
-              }
-            },
-            "files": [
-              "main.js",
-              "main.js.map",
-              "index.d.ts"
-            ],
-            "keywords": [
-              "riddl",
-              "ddd",
-              "domain-driven-design",
-              "parser",
-              "ast",
-              "typescript"
-            ],
-            "author": "Ossum Inc.",
-            "license": "Apache-2.0",
-            "repository": {
-              "type": "git",
-              "url": "https://github.com/ossuminc/riddl.git"
-            },
-            "bugs": {
-              "url": "https://github.com/ossuminc/riddl/issues"
-            },
-            "homepage": "https://github.com/ossuminc/riddl#readme",
-            "publishConfig": {
-              "access": "public"
-            }
-          }
-          EOF
-
-          # Create README
-          cat > "$OUTPUT_DIR/README.md" << 'EOF'
-          # @ossuminc/riddl-lib
-
-          RIDDL Language Library - JavaScript/TypeScript bindings for the RIDDL parser.
-
-          ## Installation
-
-          ```bash
-          npm install @ossuminc/riddl-lib
-          ```
-
-          ## Usage
-
-          ```typescript
-          import { RiddlAPI } from '@ossuminc/riddl-lib';
-
-          // Parse a RIDDL source string
-          const result = RiddlAPI.parseString(`
-            domain Banking is {
-              context Accounts is {
-                entity Account is { ??? }
-              }
-            }
-          `);
-
-          if (result.succeeded) {
-            console.log("Domains:", result.value.domains);
-          } else {
-            console.error("Errors:", RiddlAPI.formatErrorArray(result.errors));
-          }
-          ```
-
-          ## API
-
-          - `RiddlAPI.parseString(source, origin?, verbose?)` - Parse RIDDL source to AST
-          - `RiddlAPI.parseNebula(source, origin?, verbose?)` - Parse arbitrary definitions
-          - `RiddlAPI.parseToTokens(source, origin?, verbose?)` - Tokenize for syntax highlighting
-          - `RiddlAPI.validateString(source, origin?, verbose?, noANSI?)` - Full validation
-          - `RiddlAPI.version` - Library version string
-          - `RiddlAPI.buildInfo` - Detailed build information
-          - `RiddlAPI.formatErrorArray(errors)` - Format errors as string
-          - `RiddlAPI.errorsToStrings(errors)` - Convert errors to string array
-
-          ## Documentation
-
-          See [RIDDL Documentation](https://ossum.tech/riddl/) for more information.
-
-          ## License
-
-          Apache-2.0
-          EOF
-
-          echo "PACKAGE_DIR=$OUTPUT_DIR" >> $GITHUB_ENV
+      - name: Publish to GitHub Packages
+        if: github.event_name == 'release' || github.event.inputs.registry == 'github'
+        run: sbt --batch riddlLibJS/npmPublishGithub
 
       - name: Publish to npmjs.com
-        if: github.event_name == 'release' || github.event.inputs.registry == 'npmjs' || github.event.inputs.registry == 'both'
+        if: github.event.inputs.registry == 'npmjs'
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          cd "$PACKAGE_DIR"
-          npm config set //registry.npmjs.org/:_authToken "$NODE_AUTH_TOKEN"
-          npm publish --access public
-        continue-on-error: true
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: sbt --batch riddlLibJS/npmPublishNpmjs
 
-      - name: Publish to GitHub Packages
-        if: github.event_name == 'release' || github.event.inputs.registry == 'github' || github.event.inputs.registry == 'both'
+      - name: Get version for summary
+        id: version
         run: |
-          cd "$PACKAGE_DIR"
-          npm config set //npm.pkg.github.com/:_authToken "$GITHUB_TOKEN"
-          npm config set @ossuminc:registry https://npm.pkg.github.com
-
-          # Update package.json for GitHub Packages
-          jq '.publishConfig.registry = "https://npm.pkg.github.com"' package.json > package.json.tmp
-          mv package.json.tmp package.json
-
-          npm publish --access public
+          VERSION=$(sbt --batch "print riddlLibJS/version" 2>/dev/null | grep -v "\[info\]" | grep -v "loading" | tail -1 | tr -d ' ')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Generate summary
         run: |
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -112,10 +112,16 @@ The `riddlLib` module exports a TypeScript-friendly API via `RiddlAPI` object.
   - Case classes → Plain objects
   - `Either` → `{ succeeded, value, errors }`
 
-**Building npm packages**:
+**Building npm packages** (via sbt-ossuminc helpers):
+```bash
+sbt riddlLibJS/npmPrepare   # Assemble package (pure sbt)
+sbt riddlLibJS/npmPack      # Create .tgz tarball
+sbt riddlLibJS/npmPublishGithub  # Publish to GH Packages
+```
+
+**Legacy script** (still works):
 ```bash
 ./scripts/pack-npm-modules.sh riddlLib
-# Creates: npm-packages/ossuminc-riddl-lib-<version>.tgz
 ```
 
 **Documentation**:
@@ -652,3 +658,8 @@ Then add to root aggregation: `.aggregate(..., mymodule, mymoduleJS, mymoduleNat
 18. **FileBuilder requires PlatformContext** - `trait FileBuilder(using PlatformContext)` — all subclasses must propagate the using clause
 19. **Scala 3.7.4 default param limitation** - Case class defaults can't resolve givens from a subsequent using clause in generated apply; remove defaults or provide explicit givens
 20. **@JSExportTopLevel incompatible with using clauses** - Don't use on case classes that have `(using PlatformContext)` in a second parameter list
+21. **npm packaging uses sbt-ossuminc helpers** - `With.Packaging.npm()` assembles package, `With.Publishing.npm()` publishes. Tasks: `npmPrepare`, `npmPack`, `npmPublishGithub`
+22. **JS variant baseDirectory is `module/js/`** - The `npmTypesDir` convention looks for `baseDir/js/types/` which doubles to `module/js/js/types/`. Override with `.jsSettings(NpmPackaging.Keys.npmTypesDir := baseDirectory.value / "types")`
+23. **npm requires --tag for prerelease versions** - sbt-dynver versions like `1.2.3-1-hash` are prerelease per npm semver. Must pass `--tag dev` when publishing
+24. **riddlLib JS is ESModule** - Changed from CommonJS (`withCommonJSModule = true` removed). Package.json has `"type": "module"`. Consumers use `import { RiddlAPI } from '@ossuminc/riddl-lib'`
+25. **gh auth needs write:packages for npm** - Run `gh auth refresh -s write:packages` if publishing to GH Packages npm registry
diff --git a/NOTEBOOK.md b/NOTEBOOK.md
@@ -6,7 +6,7 @@ This is the central engineering notebook for the RIDDL project. It tracks curren
 
 ## Current Status
 
-**Last Updated**: February 3, 2026
+**Last Updated**: February 3, 2026 (evening)
 
 **Scala Version**: 3.7.4 (overrides sbt-ossuminc's 3.3.7 LTS default due to
 compiler infinite loop bug with opaque types/intersection types in 3.3.x).
@@ -18,6 +18,11 @@ Scala.js. Added `(using PlatformContext)` to `FileBuilder` trait and
 propagated through entire hierarchy. All tests pass. Published to
 GitHub Packages. Merged to main.
 
+**npm Package Published**: `@ossuminc/riddl-lib@1.2.3-1-aef48695-20260203-2217`
+published to GitHub Packages npm registry. ESModule format with TypeScript
+declarations. Consumable via `npm install @ossuminc/riddl-lib@dev` with
+`@ossuminc:registry=https://npm.pkg.github.com` in `.npmrc`.
+
 **Packaging Infrastructure**: Docker, npm, and TypeScript support added:
 - `Dockerfile` — Multi-stage build with custom JRE via jlink (~80-100MB image)
 - `docker-publish.yml` — CI workflow for Docker image publishing to ghcr.io
@@ -156,6 +161,56 @@ The `pseudoCodeBlock` parser now allows comments before and/or after `???`:
 
 ## Session Log
 
+### February 3, 2026 (npm Package Publishing to GitHub Packages)
+
+**Focus**: Publish `@ossuminc/riddl-lib` as npm package to GH Packages
+for consumption by Synapify and ossum.ai
+
+**Key Finding**: Most infrastructure already existed (TypeScript
+declarations, package.json template, npm-publish.yml workflow). The
+sbt-ossuminc plugin (1.2.5-4) already had `With.Packaging.npm()` and
+`With.Publishing.npm()` helpers ready to use.
+
+**Work Completed**:
+1. Updated sbt-ossuminc to 1.2.5-4-4a8a48fb-20260203-2208
+   (locally published version with npm packaging helpers)
+2. Fixed Scala.js module kind: changed from CommonJS to ESModule
+   (`withCommonJSModule = true` removed). Package.json already
+   declared `"type": "module"` so this resolved the mismatch.
+3. Wired up `With.Packaging.npm()` for riddlLibJS with scope
+   `@ossuminc`, keywords, and ESModule flag
+4. Wired up `With.Publishing.npm(registries = Seq("github"))`
+5. Fixed `npmTypesDir` convention mismatch: JS variant's
+   `baseDirectory` is `riddlLib/js/`, so convention looked at
+   `riddlLib/js/js/types/` (wrong). Overrode to
+   `baseDirectory / "types"`.
+6. Removed `export default RiddlAPI` from index.d.ts (ESModule
+   uses named exports only)
+7. Published `@ossuminc/riddl-lib@1.2.3-1-aef48695-20260203-2217`
+   to GitHub Packages npm registry with `--tag dev`
+
+**Issues Encountered**:
+- npm requires `--tag` for prerelease versions (sbt-dynver format
+  `1.2.3-1-hash-date` is a prerelease). The `NpmPublishing` helper
+  in sbt-ossuminc needs updating to handle this automatically.
+- `gh auth` needed `write:packages` scope refresh for npm publishing
+  (`gh auth refresh -s write:packages`)
+
+**Files Modified**:
+- `project/plugins.sbt` — sbt-ossuminc version bump
+- `build.sbt` — ESModule, npm packaging/publishing config, import
+- `riddlLib/js/types/index.d.ts` — removed default export
+
+**Next Steps**:
+- Simplify `.github/workflows/npm-publish.yml` to use sbt tasks
+- Fix sbt-ossuminc `NpmPublishing` to pass `--tag dev` for
+  prerelease versions
+- Test consumption from Synapify and ossum.ai
+- When ready for release, tag a clean version (e.g., `1.2.4`) to
+  get a proper semver npm version
+
+---
+
 ### February 3, 2026 (Release 1.2.3 - System.lineSeparator Fix)
 
 **Focus**: Comprehensive fix for `System.lineSeparator()` returning
diff --git a/build.sbt b/build.sbt
@@ -1,5 +1,6 @@
 import org.scoverage.coveralls.Imports.CoverallsKeys.coverallsTokenFile
 import com.ossuminc.sbt.OssumIncPlugin
+import com.ossuminc.sbt.helpers.NpmPackaging
 import com.typesafe.tools.mima.core.{ProblemFilters, ReversedMissingMethodProblem}
 import sbt.Append.{appendSeqImplicit, appendSet}
 import sbt.Keys.{description, libraryDependencies, scalacOptions}
@@ -306,8 +307,21 @@ lazy val riddlLib_cp: CrossProject = CrossModule("riddlLib", "riddl-lib")(JS, JV
   .jvmSettings(
     coverageExcludedFiles := """<empty>;$anon"""
   )
-  .jsConfigure(With.ScalaJS("RIDDL: riddl-lib", withCommonJSModule = true))
+  .jsConfigure(With.ScalaJS("RIDDL: riddl-lib"))
   .jsConfigure(With.noMiMa)
+  .jsConfigure(With.Packaging.npm(
+    scope = "@ossuminc",
+    pkgName = "riddl-lib",
+    pkgDescription = "RIDDL Language Library - JavaScript/TypeScript bindings",
+    keywords = Seq("riddl", "ddd", "domain-driven-design", "parser", "ast", "typescript"),
+    esModule = true
+  ))
+  .jsSettings(
+    NpmPackaging.Keys.npmTypesDir := Some(baseDirectory.value / "types")
+  )
+  .jsConfigure(With.Publishing.npm(
+    registries = Seq("github")
+  ))
   .nativeConfigure(With.Native(mode = "fast", buildTarget = "static"))
   .nativeConfigure(With.noMiMa)
 val riddlLib = riddlLib_cp.jvm
diff --git a/project/plugins.sbt b/project/plugins.sbt
@@ -1,7 +1,7 @@
 // GitHub Packages resolver for sbt-ossuminc
 resolvers += "GitHub Packages" at "https://maven.pkg.github.com/ossuminc/sbt-ossuminc"
 
-addSbtPlugin("com.ossuminc" % "sbt-ossuminc" % "1.2.5")
+addSbtPlugin("com.ossuminc" % "sbt-ossuminc" % "1.2.5-4-4a8a48fb-20260203-2208")
 
 // This enables sbt-bloop to create bloop config files for Metals editors
 // Uncomment locally if you use metals, otherwise don't slow down other
diff --git a/riddlLib/js/types/index.d.ts b/riddlLib/js/types/index.d.ts
@@ -387,5 +387,3 @@ export declare const RiddlAPI: {
   formatInfo: string;
 };
 
-// Default export for CommonJS compatibility
-export default RiddlAPI;
