Foss Vs Proprietary Module Pairs Agent Skill

Twin modules: <feature> and <feature>-empty

Two modules, same package, same declarations. One wraps the real integration; the other returns

values that make every caller take the "not available" path without knowing there is one.

// adapted — <feature>-empty/src/…/<Feature>.kt
package com.example.app.<feature>

// STUB build: <feature> is not available. Every function is a safe no-op so callers
// never branch on the build.

fun init<Feature>(context: Context): Boolean {
    Logger.d(TAG, UNAVAILABLE)
    return false
}

fun is<Feature>Available(): Boolean = false

fun wrapPlayer(context: Context, localPlayer: Player): Player = localPlayer

fun currentDeviceName(): String? = null

@Composable
fun <Feature>IconButton(modifier: Modifier = Modifier, tint: Color = Color.White) {
    // no-op
}

Selection is a Gradle property, read the same way in every consuming module:

// adapted — top of each consuming build script
val isFullBuild: Boolean = try { extra["isFullBuild"] == "true" } catch (e: Exception) { false }

// …in that module's dependency block
if (isFullBuild) implementation(projects.<feature>) else implementation(projects.<feature>Empty)

The property has a default in gradle.properties; continuous integration appends a line to that same

file before invoking Gradle, one value per job — run: echo "isFullBuild=false" >> ./gradle.properties.

Why a property, not product flavors

Product flavors are an Android Gradle Plugin concept. A Kotlin Multiplatform module's jvm(),

ios*() and common source sets have no flavor dimension, so a flavor cannot select a dependency for

them — and here the twins are consumed from *both* an Android-only module and the commonMain

dependency block of a multiplatform module. One property covers every module and every target; a

flavor covers a subset and silently leaves the rest on whichever twin was hardcoded.

Traps

Every consuming module must read the same property, or the graph mixes. The gate is per-module,

so one module that hardcodes the real twin drags the proprietary code into the open build through a

transitive path — and it links fine, so nothing complains. Enumerate both sides and compare:

grep -rn 'isFullBuild' --include='*.kts' --include='*.properties' --include='*.yml' . | grep -v '/build/'
grep -rn '<feature>Empty\|<feature>-empty' --include='*.kts' . | grep -v '/build/'

Every module in the second list must also appear in the first. Here the pairs are gated from build

scripts across the whole tree, including one deep in the data layer that nothing about the user

interface would have led you to.

Both twins declare the same package *and* the same Android namespace — that is what makes the

swap invisible: imports do not change, so no call site knows which module it linked against.

The stub returns identity, never null, wherever the real one transforms. wrapPlayer handing

back localPlayer unchanged is the shape to copy. A stub returning null there forces every caller

into a branch — the thing this pattern exists to delete.

The availability check is the entire hiding mechanism. The stub's is<Feature>Available()

returns a hardcoded false; the real one derives it from whether the credential was injected:

fun is<Feature>Available(): Boolean = apiKey.isNotEmpty() && sharedSecret.isNotEmpty()

That second form is what makes a full build *without* credentials behave exactly like the stub build

instead of offering a login that can never succeed. Pair it with buildkonfig-secrets-flavors, which

supplies the empty strings on the no-secrets branch. Then confirm the check is consulted —

grep -rn 'is<Feature>Available()' --include='*.kt' . | grep -v '/build/' should hit at least the

settings screen (so the whole block hides) and the service entry point (so background work returns

early).

The stub needs enough to compile the same signatures, and nothing from the vendor. The stub here

carries the neutral type artifact for the player interface, the Compose runtime for the composable,

and the project's own shared modules — but no proprietary artifact. Read the difference directly

rather than assuming it, and match the declarations wherever they sit: a multiplatform twin keeps

them indented inside sourceSets { … { dependencies { … } } }, where a /^dependencies {/ capture

matches zero lines and the diff passes silently.

deps() { grep -hoE '^[[:space:]]*(implementation|api|compileOnly|runtimeOnly)\(.*' "$1" \
           | sed 's/^ *//' | sort; }
diff <(deps <feature>/build.gradle.kts) <(deps <feature>-empty/build.gradle.kts)

Lines only on the proprietary side should be the vendor's artifacts. Lines only on the *stub* side

are not automatically drift — a stub often needs a shared or logging module the real twin gets

transitively — so read each one rather than deleting it.

Missing declarations only fail in the branch you are not building. The two files are kept in

lockstep by hand, so a function added to the real twin and forgotten in the stub compiles locally and

fails elsewhere. Data classes, sealed hierarchies and constants count: the stub here re-declares the

full result hierarchy including its error codes, because callers pattern match on them.

Reading the property must not fail when it is absent. The try/catch defaulting to false is

deliberate — a module with no property in scope gets the stub, the branch that always builds. The

checked-in default may still be the *full* build, as it is here, but that is only safe because the

credential reader catches a missing local.properties and writes empty fields, which the

availability check above turns back into stub behaviour. Without that catch, defaulting to full

makes a contributor's first build fail on a missing credential.

A stub is not a place for TODOs. These functions are called from playback callbacks and from

composition, so every one must be complete and safe on a hot path. One log line per call is fine;

throwing, or returning a partially initialised object, is not.

Verifying it

# the two public surfaces must declare the same names.
# The final `sort` is load-bearing: `uniq -u` only collapses ADJACENT duplicates, so two
# separately sorted lists concatenated make it report every declaration as one-sided.
for m in <feature> <feature>-empty; do
  grep -rhoE '^(fun|suspend fun|data class|sealed interface|@Composable)[^({]*' "$m/src" | sort
done | sort | uniq -u    # must print nothing — anything listed exists on one side only

# both twins stay in the project list unconditionally; selection happens per dependency
grep -n '<feature>' settings.gradle.kts

That second point matters. Conditionally include()-ing a project makes the whole configuration

depend on the property, which breaks tooling that resolves the project list without one.