Engineering Notebook: sbt-ossuminc

Incoming Tasks

At session start, check the task/ directory for pending work requests from other projects. Each .md file describes a task (e.g., dependency upgrade). Treat unresolved tasks as to-do items unless already completed (verifiable from this notebook, CLAUDE.md, or git log). After completing a task, append results to the task file and note completion in this notebook.

Current Status

Version 1.3.5 released (Feb 20, 2026). No active work items.

Previous releases: v1.3.4, v1.3.3, v1.3.2, v1.3.0, v1.2.5.

Work Completed (Recent)

Session Feb 20, 2026 — Corporate Name Fix & Release Improvements

Released: v1.3.4 and v1.3.5 to GitHub Packages.

v1.3.4 — orgName fix:

Changed default orgName from "Ossum, Inc." to "Ossum Inc." (no comma) in Root.scala, RootProjectInfo.scala, and test build files. Fixed typo "Ossumin, Inc." in program test.
Cross-project task from riddl Claude instance (task/fix-orgname-comma.md).

v1.3.5 — Copyright, tests, and workflow:

Updated all source file copyright dates to 2015-2026 (were stale at 2015-2017 in most files).
Fixed docker-dual scripted test assertions to expect Artifact Registry defaults (us-central1-docker.pkg.dev and ossuminc-production/ossum-images) instead of old ghcr.io.
Changed release workflow trigger from tag push to release creation (on: release: types: [created]), matching the riddl project pattern. Added workflow_dispatch for manual triggering.

All 20 scripted tests passing (docker-dual was previously broken due to stale assertions from the Artifact Registry default change).

Session Feb 16, 2026 — Release Workflow

Added .github/workflows/release.yml to automate GitHub Releases with artifact attachment. Triggers on tag pushes matching [0-9]*. Runs sbt clean test publish (JDK 25 Temurin), collects the plugin JAR, and creates a GitHub Release with auto-generated release notes and the JAR attached for download.

Session Feb 3, 2026 — v1.3.0 Released

Implemented complete packaging infrastructure across 6 phases. Integration-tested in riddl project (npm packaging/publishing to npmjs.com for ossum.ai site consumption). See PACKAGING-PLAN.md for the original design document.

New helpers:

With.Packaging.npm() — npm package assembly from Scala.js output
With.Publishing.npm() — publish to npmjs.com and/or GitHub Packages
With.Packaging.linux() — tar.gz archives of Scala Native binaries
With.Packaging.homebrew() — Homebrew formula generation (JVM/Native)
With.Packaging.windowsMsi() — placeholder for future implementation

New files: NpmPackaging.scala, NpmPublishing.scala, HomebrewPackaging.scala

Modified files: Packaging.scala (added linux(), npm(), homebrew(), windowsMsi() delegation + linuxPackage keys), Publishing.scala (added npm() delegation)

New scripted tests: npm-packaging, linux-packaging, homebrew (20 total, all passing)

Session Feb 2, 2026 — Docker Dual-Image Support

Added With.Packaging.dockerDual() for separate dev/prod Docker images. Dev image uses eclipse-temurin:25-jdk-noble (arm64), prod uses gcr.io/distroless/java25-debian13:nonroot (amd64). Scripted test added.

Session Jan 28-29, 2026 - v1.2.5 Released (CI Fixes)

Released: v1.2.5 to GitHub Packages

Root Cause Analysis: The scripted tests had been failing since PR #8 "Use native git instead of JGit for worktree support". Native git fails hard in non-git directories, while JGit was more lenient. Scripted tests run in temp directories that aren't git repositories.

Bug Fixes:

Git/DynamicVersioning helpers now detect git repos - Added isGitRepo check that walks up directory tree looking for .git. Only enables native git (useReadableConsoleGit) if actually in a git repo. Falls back to JGit for non-git directories (scripted tests).
AKKA_REPO_TOKEN propagation to scripted tests - The scriptedLaunchOpts now passes AKKA_REPO_TOKEN as system property -Dakka.repo.token=.... The Akka helper checks both sys.props and sys.env for the token.
Modules now apply Resolvers - Module() was missing the Resolvers configuration, breaking dependency resolution for Akka dependencies.

Improvements:

Updated scripted test build.sbt files to use modern PascalCase With.* syntax (BuildInfo, Scala3, Riddl) instead of deprecated lowercase versions.

Technical Notes:

The isGitRepo function is duplicated in both Git.scala and DynamicVersioning.scala because the project/ directory uses symlinks to the source files, and DynamicVersioning.scala is linked while Git.scala is not. Sharing the function would require adding another symlink.
CI now passes all 16 scripted tests.

Session Jan 27, 2026 - Documentation Updates

Improved documentation for With.Akka helper to reduce confusion for users:

Updated CLAUDE.md to direct users to README.md as authoritative source
Updated version references from 1.0.0/1.2.0 to 1.2.4 in both files
Documented all With.Akka.forRelease boolean parameters in README.md
Added note for riddl-server-infrastructure dependents explaining when to use With.Akka (only needed for modules beyond what server infrastructure provides)
Included examples for basic and full-featured Akka configurations

Session Jan 24, 2026 - v1.2.4 Released

Released: v1.2.4 to GitHub Packages

Added withInsights and withManagementKubernetes parameters to With.Akka.forRelease():

New Features:

withInsights - Adds Cinnamon telemetry modules (actor, HTTP, cluster metrics)
withInsightsPrometheus - Prometheus metrics export (default: true)
withInsightsOpenTelemetry - OpenTelemetry tracing (default: true)
withManagementKubernetes - K8s discovery, lease, rolling updates

Implementation:

Added javaModule() helper for Java-only dependencies (no Scala suffix)
Added insightsModules() function with all Cinnamon dependencies
Added managementKubernetesModules() function
Uses direct Maven coordinates instead of sbt-cinnamon plugin

Technical Notes:

Cinnamon Scala modules: cinnamon-akka, cinnamon-akka-typed, cinnamon-akka-stream, cinnamon-akka-cluster, cinnamon-akka-http
Cinnamon Java modules: cinnamon-prometheus, cinnamon-prometheus-httpserver, cinnamon-opentelemetry, cinnamon-agent
K8s modules: akka-discovery-kubernetes-api, akka-lease-kubernetes, akka-rolling-update-kubernetes

CI Note: Scripted tests failing in CI due to "Remote sbt initialization failed" error affecting all 15 tests. This is a pre-existing CI environment issue, not related to these changes. Used manual sbt publish for release.

Session Jan 17, 2026

Refactored AutoPluginHelper to extend (Project => Project) for better UX
Made CrossModule dependencies optional (breaking change)
Created With.ScalaJavaTime() helper for opt-in java.time support
Created With.Publishing helper (defaults to GitHub, .sonatype option)
Improved Root requirement error messages for publishing helpers
Parameterized dependency versions in ScalaJS and Native helpers
Added scripted tests: scalatest, publishing (now 16/16 passing)
Verified Akka and IntelliJ plugin tests pass (were already working)

Previous Sessions

Resolved Issues

GitHub Packages resolution for sbt plugins (FIXED)

Problem: Other projects couldn't resolve sbt-ossuminc from GitHub Packages.

Root cause: README was missing resolver configuration. GitHub Packages is not in sbt's default resolver chain, so consumers must explicitly add it.

Solution: Updated README to include resolver in project/plugins.sbt:

resolvers += "GitHub Packages" at
  "https://maven.pkg.github.com/ossuminc/sbt-ossuminc"
addSbtPlugin("com.ossuminc" % "sbt-ossuminc" % "1.1.0")

Plus credentials in ~/.sbt/1.0/github.sbt.

Next Steps (Priority Order)

🟡 REMAINING WORK

1. Remove or implement NodeTarget

File: CrossModule.scala (lines 21, 76-80)

Dead code - NodePlatform.enable does nothing. Either remove entirely or implement properly.

2. Expose Miscellaneous helpers in With object

File: OssumIncPlugin.scala

Add to With object:

val ClassPathJar = Miscellaneous.useClassPathJar _
val UnmanagedJars = Miscellaneous.useUnmanagedJarLibs _
val ShellPrompt = Miscellaneous.buildShellPrompt

3. Clarify composite helpers

Document what basic, typical, everything include. Consider if typical should include publishing by default.

4. Make Root project ID configurable

File: Root.scala (line 38)

Currently hardcoded to "root". Add parameter:

def apply(
  projectId: String = "root",  // New parameter
  ghRepoName: String = "",
  // ... rest
): Project

5. Remove placeholder Packaging methods

File: Packaging.scala

jdkPackager(), linuxDebian(), linuxRPM() do nothing. Either implement or remove.

6. Remove `project/SonatypePublishing.scala`

No longer used after switching to GitHub Packages.

7. Update CI workflow to use JDK 25

Release workflow uses JDK 25 Temurin; CI still uses JDK 21 adopt-hotspot. Consider aligning.

Test Coverage Status

Current Test Results (Feb 3, 2026)

Test Scenario	Purpose	Status
akka	Akka dependencies	✅ PASS
asciidoc	AsciiDoc document generation	✅ PASS
basic	Basic module configuration	✅ PASS
cross	Cross-platform (JVM/JS/Native)	✅ PASS
docker-dual	Dev/prod Docker images	✅ PASS
everything	Full feature set	✅ PASS
homebrew	Homebrew formula generation	✅ PASS
idea-plugin	IntelliJ plugin development	✅ PASS
laminar	Laminar UI dependencies	✅ PASS
linux-packaging	Native binary tar.gz archive	✅ PASS
mima	Binary compatibility checking	✅ PASS
multi	Multi-module projects	✅ PASS
native	Scala Native compilation	✅ PASS
npm-packaging	npm package assembly	✅ PASS
packaging	Universal packaging	✅ PASS
program	Executable programs	✅ PASS
publishing	Publishing helper	✅ PASS
scalably-typed	TypeScript facades	✅ PASS
scalajs	Scala.js compilation	✅ PASS
scalatest	Scalatest helper	✅ PASS

Pass rate: 20/20 (100%)

Missing Test Coverage

Tests needed for:

With.MiMa() - Binary compatibility checking
With.Packaging.docker() - Docker image creation
With.Packaging.graalVM() - GraalVM native images
With.Riddl() - RIDDL library dependencies
With.Laminar() - Laminar UI dependencies
With.Scalatest() - Custom ScalaTest versions
With.Scala3() - Custom Scala 3 configurations
With.BuildInfo() - Custom BuildInfo settings
With.Unidoc() - Custom Unidoc configurations
With.coverage() - Code coverage thresholds

Test Infrastructure Improvements Needed

Version-agnostic tests - Don't hardcode Scala versions
CI integration - Run scripted tests on every PR
Cross-version testing - Test with sbt 1.10.x, 1.11.x, 1.12.x
Cross-Scala testing - Test with Scala 2.13.x, 3.3.x, 3.4.x

Long-Term Vision (v2.0.0)

Goals

Stability: No breaking changes for 12+ months after release
Consistency: All helpers follow same PascalCase naming patterns
Documentation: Every helper fully documented with examples
Discoverability: IDE autocomplete reveals all features
Testing: 100% helper coverage in scripted tests
Examples: Real-world examples for every use case

Potential Future Features

With.Metals() - Metals LSP configuration
With.VSCode() - VS Code settings generator
With.CI.github() - GitHub Actions workflow generator
With.CI.gitlab() - GitLab CI pipeline generator
With.Docker.compose() - Docker Compose for dev environment
With.Kubernetes() - K8s manifests generator
With.Observability() - Metrics, tracing, logging setup
Interactive wizard: sbt ossuminc:new to scaffold projects

Proposed Examples Directory

Create examples/ with working build.sbt files:

basic-library/ - Simple library project
cross-platform/ - JVM+JS+Native project
executable/ - Program with packaging
idea-plugin/ - IntelliJ IDEA plugin
monorepo/ - Multi-module project

Design Decisions Log

Decision	Rationale	Date
Delegation pattern for new helpers	Keeps API at `With.Packaging.npm()` not `With.NpmPackaging`	2026-02-03
`fullOptJS` for npm packaging	Closure Compiler optimization needed; not deprecated	2026-02-03
`Def.task` for variant selection	sbt `.value` macro resolves all refs in task body	2026-02-03
Auto-detect OS/arch for linux()	Scala Native compiles for host only; CI matrix for multi-arch	2026-02-03
No JSON library for package.json	Avoids dependency; string builder sufficient for Scala 2.12	2026-02-03
Switch Sonatype → GitHub Packages	Simpler auth for ossuminc org	2026-01-15
Use symlink approach	Consistent with project/ pattern	2026-01-15
Rename With.Javascript → With.ScalaJS	Clearer naming	2026-01-15
Tag format without `v` prefix	sbt-dynver compatibility	2026-01-15
Keep sbt-header at 5.10.0	5.11.0 has breaking imports	2026-01-08

Project Structure Notes

The project/ directory uses symlinks to reference helper files from src/main/scala/com/ossuminc/sbt/helpers/. This allows the plugin to use its own functionality during its own build (bootstrapping).

Current symlinks in project/:

AutoPluginHelper.scala → helpers source
DynamicVersioning.scala → helpers source
GithubPublishing.scala → helpers source (added for 1.1.0)
Miscellaneous.scala → helpers source
Release.scala → helpers source
RootProjectInfo.scala → helpers source
Scala2.scala → helpers source
SonatypePublishing.scala (local file, not symlink - can be removed)

Migration Notes (for Breaking Changes)

v1.2.0 Migration (from 1.1.0)

CrossModule dependency changes (BREAKING):

// Old (1.1.0 - automatic dependencies)
CrossModule("foo", "bar")(JVM, JS)

// New (1.2.0 - explicit dependencies)
CrossModule("foo", "bar")(JVM, JS)
  .configure(With.Scalatest())      // If you want testing
  .configure(With.ScalaJavaTime())  // If you need java.time

New helpers available:

With.Publishing - Generic publishing (defaults to GitHub)
With.Publishing.github - Explicit GitHub Packages
With.Publishing.sonatype - Explicit Sonatype/Maven Central
With.ScalaJavaTime() - Add scala-java-time dependency

Parameterized versions now supported:

// ScalaJS and Native helpers now accept version parameters
With.ScalaJS(
  scalaJavaTimeVersion = "2.6.0",  // Override default
  scalatestVersion = "3.2.19"      // Override default
)

With.Native(
  scalatestVersion = "3.2.19"      // Override default
)

Future v2.0.0 Migration

Naming convention changes (deprecated in 1.x, removed in 2.x):

// Old (deprecated)
.configure(With.build_info)
.configure(With.GithubPublishing)

// New (required in 2.x)
.configure(With.BuildInfo())
.configure(With.GitHubPublishing)

Uh oh!

FilesExpand file tree

NOTEBOOK.md

Latest commit

History