ketoy-dev 0.1.0

package/skills/ketoy/examples/todo-screen.kt

@@ -0,0 +1,156 @@
+// CANONICAL KBC SCREEN — copy this shape verbatim for new screens.
+//
+// This is an excerpt from the Ketoy repo's `app/.../ketoyscreens/TodoListScreen.kt`,
+// trimmed to highlight the patterns that matter. Every line is exercised by
+// the real Phase 11E in-tree app-module export pipeline.
+//
+// Key things to notice:
+// 1. Annotations: @KetoyEntryPoint + @KetoyComposable + @Composable on the root.
+// 2. Outer-scope `val title` captured into the Column content lambda — proves
+//    closure conversion works (KBCValue.ClosureRef under the hood).
+// 3. Modifier chains use named args (padding(horizontal=, vertical=), etc.).
+// 4. Color via literal `Color(0xff4F378B)` or named `Color.White`.
+// 5. Shapes always `RoundedCornerShape(N.dp)` or `RoundedCornerShape(percentInt)`.
+// 6. Images: `painterResource(R.drawable.X)` — host must register X.
+// 7. Custom font: `FontFamily(Font(R.font.X))` — host must register X.
+// 8. No vars, no state-holding objects, no LaunchedEffect-with-mutable-closure.
+
+package com.example.app.ketoyscreens
+
+import androidx.compose.foundation.Image
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.Card
+import androidx.compose.material3.CardDefaults
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.TopAppBarDefaults
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.res.painterResource
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import com.example.app.R
+import dev.ketoy.annotations.KetoyComposable
+import dev.ketoy.annotations.KetoyEntryPoint
+
+@OptIn(ExperimentalMaterial3Api::class)
+@KetoyEntryPoint
+@KetoyComposable
+@Composable
+public fun TodoListScreen(modifier: Modifier = Modifier) {
+    // Captured into content lambdas via closure conversion.
+    val title = "Ketoy Todo"
+    val subtitle = "Shipped as .ktx bundle"
+
+    Scaffold(
+        modifier = Modifier.fillMaxSize(),
+        topBar = {
+            TopAppBar(
+                title = { Text(title, color = Color.White) },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = Color(0xFF4F378B),
+                ),
+            )
+        },
+        floatingActionButton = {
+            Button(
+                onClick = { navPush("todo_add") },  // capability call
+                modifier = Modifier.padding(16.dp),
+                shape = RoundedCornerShape(100),
+                colors = ButtonDefaults.buttonColors(
+                    containerColor = Color(0xff4F378B),
+                    contentColor = Color.White,
+                ),
+            ) {
+                Text("+", fontSize = 24.sp)
+            }
+        },
+    ) { paddingValues ->
+        Column(
+            modifier = Modifier
+                .padding(paddingValues = paddingValues)
+                .fillMaxSize()
+                .padding(horizontal = 20.dp, vertical = 20.dp),
+        ) {
+            Card(
+                modifier = Modifier.fillMaxWidth(),
+                shape = RoundedCornerShape(40.dp),
+                colors = CardDefaults.cardColors(containerColor = Color(0xFFB69DF8)),
+            ) {
+                Row(
+                    modifier = Modifier.fillMaxSize(),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.Center,
+                ) {
+                    Text(
+                        text = "Hello, $title!",
+                        fontSize = 28.sp,
+                        fontWeight = FontWeight.Bold,
+                        color = Color.White,
+                    )
+                }
+            }
+
+            Spacer(modifier = Modifier.height(20.dp))
+
+            // Decorative image — host registers "img" → R.drawable.img
+            Image(
+                painter = painterResource(R.drawable.img),
+                contentDescription = subtitle,
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .height(120.dp)
+                    .clip(shape = RoundedCornerShape(20.dp)),
+            )
+
+            Spacer(modifier = Modifier.height(20.dp))
+
+            // Custom font — host registers "courgette_regular" → R.font.courgette_regular
+            Text(
+                text = subtitle,
+                fontSize = 16.sp,
+                fontWeight = FontWeight.SemiBold,
+                fontFamily = FontFamily(Font(R.font.courgette_regular)),
+                color = Color.Black,
+            )
+
+            Spacer(modifier = Modifier.height(20.dp))
+
+            Box(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .height(100.dp)
+                    .clip(shape = RoundedCornerShape(30))
+                    .background(color = Color(0xffFFECF1)),
+                contentAlignment = Alignment.Center,
+            ) {
+                Text(
+                    text = "Bottom panel",
+                    fontSize = 14.sp,
+                    color = Color(0xFFD0706B),
+                    fontWeight = FontWeight.Bold,
+                )
+            }
+        }
+    }
+}

package/skills/ketoy/guides/build-and-analyze.md

@@ -0,0 +1,87 @@
+# Build and Analyze Ketoy Bundles
+
+## Build
+
+The bundle is produced as part of the host APK build:
+
+```bash
+./gradlew :app:ketoyBundle --rerun-tasks           # compile KBC only (faster iteration)
+./gradlew :app:assembleDebug         # full APK (transitively triggers ketoyBundle)
+./gradlew :app:assembleRelease       # signed release APK
+```
+
+Bundle output path: `app/src/main/assets/ketoy/main.ktx`
+
+Successful build logs end with:
+```
+KetoyBC: Compilation complete — N functions emitted, M composables, K view models, J entry points.
+Bundle ID: main. Wrote NNNN bytes to ... (signed)
+```
+
+The `(signed)` suffix is present only when `signingKeyFile` was supplied. Unsigned bundles work in development but should never ship to a release APK (the host runtime will reject them when `enableSignatureVerification = true`).
+
+## Analyze a `.ktx` bundle
+
+The CLI `analyze <path>` subcommand wraps a JVM subprocess that calls `KtxReader.read` and prints:
+
+- Format version
+- Bundle ID
+- Function count, composable count, view-model count, entry-point count
+- String pool size + contents (with `--strings`)
+- Adapter manifest (with `--manifest`)
+- Constructor manifest
+- Capability manifest
+- Modifier table entry count
+- Signature present (yes/no)
+- Minimum runtime version
+
+Implementation sketch — under the hood it runs:
+```bash
+java -cp <ketoy-bundle-format-jar>:<ketoy-bytecode-jar> \
+  -Dktx.path=path/to/main.ktx \
+  dev.ketoy.bundle.KtxInspectorMain
+```
+
+If you don't have `KtxInspectorMain`, write a tiny one — it's ~30 lines using `KtxReader.read(bytes, verifySignature = false)` + pretty-printing.
+
+## Quick byte-level proofs
+
+For diagnosing wire-format issues:
+
+```bash
+# magic bytes — must be 4B 54 4F 59 ("KTOY")
+xxd -l 4 app/src/main/assets/ketoy/main.ktx
+
+# format version (offset 4, big-endian u16) — should be 0x0002
+xxd -s 4 -l 2 app/src/main/assets/ketoy/main.ktx
+
+# bundle has signature trailer? last 64 bytes should be non-zero
+xxd -s -64 -l 64 app/src/main/assets/ketoy/main.ktx
+
+# scan string pool for unwanted references — should NOT contain raw Compose getter FQs
+strings -n 4 app/src/main/assets/ketoy/main.ktx | grep '<get-'
+```
+
+The last command is a regression canary: if it prints anything, the compiler-plugin's encoder short-circuits aren't catching some token / icon / font / drawable reference and the bundle is carrying dead getter strings.
+
+## Bundle delivery options
+
+A built `.ktx` can be consumed via four `KetoyBundleSource` variants:
+
+| Source | Use case | Caching |
+|---|---|---|
+| `KetoyBundleSource.Asset("ketoy/main.ktx")` | Default — ship inside APK | None (APK is the cache) |
+| `KetoyBundleSource.Preloaded(bundle)` | Warm-up, tests, custom caches | Caller-managed |
+| `KetoyBundleSource.Raw(bytes)` | Manual byte handoff | Caller-managed |
+| `KetoyBundleSource.Remote(url, headers)` | CDN delivery, hot updates | ETag-based, `context.cacheDir/ketoy_bundles/` |
+
+For production server-driven delivery, build the bundle in CI, sign it with the production key, upload to your CDN, and use `Remote(url)`. The host verifies the signature on every load.
+
+## Bundle size optimization
+
+- Brotli compression is on by default for CODE / MODIFIER_TABLE / DEBUG_INFO sections.
+- `debugMode = false` strips DEBUG_INFO (saves ~10% on typical bundles).
+- Trim unused capability stubs from `Capabilities.kt` — every declared stub adds to the manifest.
+- String pool dedup is automatic; same string used N times costs 1 entry.
+
+A sample-app bundle today is ~3.5 KB signed. A real production screen with 20+ widgets, 5 fonts, 3 drawables, and 15 capabilities is typically 8–25 KB.

package/skills/ketoy/guides/diagnose-errors.md

@@ -0,0 +1,129 @@
+# Diagnose Ketoy Errors
+
+The Ketoy compiler plugin emits typed diagnostics with `KetoyBC:` prefix, a rationale, a `Fix:` block, a `Docs:` link, and (for transitive errors) a `Reached via:` call-chain breadcrumb. **Always show the user the full error text** — don't paraphrase.
+
+## Compile-time errors
+
+### `KetoyBC: Direct access to <android.X> ...`
+
+A KBC screen called an Android API. Fix: add a `@KetoyCapabilityStub` for the operation and route through it.
+
+Find the call site (use the breadcrumb's leaf). Examples:
+
+| Banned call | Replacement |
+|---|---|
+| `Toast.makeText(...).show()` | `toast(msg)` capability |
+| `Vibrator.vibrate(...)` | `vibrate(ms)` capability |
+| `Log.d(tag, msg)` | `log(tag, msg)` capability |
+| `context.startActivity(intent)` | `openUrl(uri)` or custom capability |
+
+### `KetoyBC: Reflection is not allowed in KBC source`
+
+Replace with sealed classes + exhaustive `when`. KBC has no runtime type metadata.
+
+### `KetoyBC: File I/O is not allowed in KBC source`
+
+Use `kvGet/kvSet` (DataStore-backed) or `dbQuery/dbObserve` (Room-backed via `KBCRoomBridge`).
+
+### `KetoyBC: GlobalScope is forbidden — use viewModelScope`
+
+Allowed alternatives:
+- Inside `@KetoyComposable`: `LaunchedEffect(key) { ... }`
+- Structured concurrency: `coroutineScope { ... }`
+- Background work via `withContext(Dispatchers.IO) { ... }` (uses `DISPATCHER_IO` capability)
+
+### `KetoyBC: Unregistered composable <FQ>`
+
+The composable isn't in the adapter scan-roots. Two paths:
+1. **Same-module helper** — add `@KetoyComposable` so it becomes a KBC function (the closure walk auto-includes it via reachability).
+2. **External composable not in the catalog** — either inline the body or write a custom `KBCComposableAdapter` host-side.
+
+### `KetoyBC: Unregistered capability <name> id=0xXXXX`
+
+The stub references a capability ID that doesn't appear in `ketoy-capabilities.json`. Add it:
+
+```json
+{ "id": 16385, "name": "YOUR_CAP",
+  "fqName": "com.example.app.ketoyscreens.yourCap",
+  "kind": "SUSPEND", "required": true }
+```
+
+(Decimal IDs in JSON: `0x4001` = `16385`.)
+
+### `KetoyBC: Direct construction of <FQ>`
+
+A constructor not in `reference/supported-constructors.md`. Options:
+- Use a supported alternative.
+- Move construction host-side; pass via state.
+- Custom `KBCConstructorAdapter` (advanced).
+
+### `KetoyBC: Direct access to <Token>.<get-X>` (e.g. `FontWeight.<get-Bold>`)
+
+The token isn't in `ComposeTokenRegistry`. The standard Compose tokens (FontWeight.Bold/Medium/SemiBold/Normal/Light/Thin/ExtraBold/ExtraLight/Black) ARE supported — if you see this, you're likely using a non-standard FontWeight subclass or a 0.x version mismatch. Verify your `compose-material3` BOM matches what `ketoy-adapters-material3` was generated against.
+
+## Transitive errors with breadcrumbs
+
+```
+KetoyBC: Direct access to android.util.Log.d
+  Reached via: TodoListScreen → renderHeader → trackImpression
+  ...
+```
+
+**Fix at the leaf** (`trackImpression`), not the root. The breadcrumb is the path you need.
+
+If the leaf is genuinely necessary and shouldn't be migrated, mark the helper non-KBC by removing its `@KetoyComposable` annotation AND ensuring no KBC root calls it. Then it compiles to plain DEX in the same `:app` module — totally fine.
+
+## Bundle build errors
+
+### `Could not find dev.ketoy.compiler:dev.ketoy.compiler.gradle.plugin`
+
+The plugin isn't published / not on classpath. Verify:
+- `settings.gradle.kts` includes `mavenCentral()` in `pluginManagement.repositories`
+- Gradle plugin version matches the runtime version (both `0.2.1-alpha`)
+
+### `Task 'ketoyBundle' not found in project ':app'`
+
+The `dev.ketoy.compiler` plugin isn't applied. Add `id("dev.ketoy.compiler")` to `app/build.gradle.kts`.
+
+### `Unsigned bundle warning` in build output
+
+Your `signingKeyFile` is missing. Generate one (see `guides/init-project.md` step 8) or accept unsigned bundles (development only — host must set `enableSignatureVerification = false`).
+
+## Runtime errors
+
+### `KetoyBundleMalformedException: Invalid magic bytes`
+
+The `.ktx` file is corrupt or not a KBC bundle. Rebuild via `./gradlew :app:ketoyBundle --rerun-tasks`.
+
+### `KetoyBundleSignatureException: Signature verification failed`
+
+The public key in the APK doesn't match the private key used at compile time. Either:
+- Regenerate both halves (see init step 8) and rebuild.
+- Set `enableSignatureVerification = false` in `KetoyConfig` (dev only).
+
+### `KetoyBundleVersionException: Bundle requires runtime version N`
+
+The bundle was compiled against a newer Ketoy runtime than the host APK ships. Bump the `dev.ketoy.vm:*` dependency versions in the host.
+
+### `KetoyMissingCapabilityException: capability id=0xXXXX (NAME) not registered`
+
+The host's `CapabilityRegistry` doesn't have a registration for that ID. Add it inside `KetoyCapabilityProvider.buildRegistry()` or wherever you build the registry.
+
+### `KBCEngineNotAvailableException: Coroutine engine`
+
+Trying to call a `suspend` capability without wiring `parentScope` into the VM. Use `KetoyVirtualViewModel` (which provides `viewModelScope`) — `KetoyScreen` does this automatically.
+
+### `KetoyMissingAdapterException: adapter id=0xXXXX`
+
+The bundle was compiled with a composable adapter that the host doesn't ship. If you added `dev.ketoy.vm:ketoy-adapters-material3`, you have the full Material3 set. Check that you haven't introduced a custom adapter compile-side without registering it runtime-side.
+
+### `ClosureRef captures > N registers`
+
+Closure conversion captured too many outer-scope locals. Refactor to fewer captures — typically by computing values inline or via state.
+
+## When you don't recognize the error
+
+1. Search this skill's `reference/` files for matching FQ names.
+2. Search the Ketoy repo's `KNOWN_ISSUES.md` — there are 12+ known limitations documented with workarounds.
+3. Read `CLAUDE.md` at the repo root — every phase has a "Key Technical Decisions" block that often explains weird behavior.
+4. Search the `ketoy-compiler-plugin/src/main/.../KetoyCompilationError.kt` source for the diagnostic message text — the variant class points at the validator path that produced it.

package/skills/ketoy/guides/init-project.md

@@ -0,0 +1,127 @@
+# Init a new Ketoy-enabled project
+
+The `ketoy init` command is **deterministic and AI-free**. It makes **surgical, additive edits** to existing user files and creates new files only where none exist. **Never rewrite an existing `build.gradle.kts`, `AndroidManifest.xml`, `MainActivity.kt`, or `Application` class in full** — that would destroy the user's existing dependencies, signing config, theme, etc. See [safe-edits.md](safe-edits.md) for the per-file insertion strategy. Templates in `templates/` describe the *final shape*; they are NOT the bytes to write into existing files.
+
+## Inputs to collect
+
+1. **Existing project?** — detect via `settings.gradle.kts` + `app/build.gradle.kts`. If neither exists, suggest using `gradle init` or Android Studio first; Ketoy is an add-on, not a project generator.
+2. **Hilt or not?** — grep `app/build.gradle.kts` and any `*.kt` for `dagger.hilt`. Default to NO if not detected.
+3. **Application ID & namespace** — read from existing `app/build.gradle.kts`.
+4. **Package** for `ketoyscreens/` — same as namespace by default.
+5. **minSdk** — must be 26+. If existing is below, abort and tell user.
+
+## Steps the `init` command performs
+
+### Step 1 — Surgically edit `app/build.gradle.kts` (never overwrite)
+
+Three additive edits — see [safe-edits.md § app/build.gradle.kts](safe-edits.md) for exact insertion anchors:
+
+- Insert `id("dev.ketoy.compiler")` at the end of the existing `plugins { }` block (skip if already present).
+- Append a `// Ketoy` dependency group at the end of the existing `dependencies { }` block — never touch the user's existing entries.
+- Append the `ketoy { ... }` block AFTER the last `}` of the file. Don't insert mid-file.
+- If `minSdk < 26` → STOP and ask. Don't silently bump.
+- Never touch `android { }`, `defaultConfig { }`, `buildTypes { }`, `compileOptions`, signing configs, or custom blocks.
+
+### Step 2 — Create `app/ketoy-capabilities.json`
+
+Use `templates/ketoy-capabilities.json.tmpl`. Substitute `{{PACKAGE}}` with the namespace.
+
+### Step 3 — Create `app/src/main/.../ketoyscreens/`
+
+- `Capabilities.kt` — copy from `examples/capabilities-stubs.kt`, package-rebase to `{{PACKAGE}}.ketoyscreens`.
+- `HelloKetoyScreen.kt` — a minimal `@KetoyEntryPoint @KetoyComposable` screen so the bundle has something to compile:
+
+```kotlin
+package {{PACKAGE}}.ketoyscreens
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import dev.ketoy.annotations.KetoyComposable
+import dev.ketoy.annotations.KetoyEntryPoint
+
+@KetoyEntryPoint
+@KetoyComposable
+@Composable
+public fun HelloKetoyScreen() {
+    Column(
+        modifier = Modifier.fillMaxSize().padding(20.dp),
+    ) {
+        Text(text = "Hello, Ketoy!", fontSize = 24.sp)
+        Text(text = "This screen shipped as a .ktx bundle.")
+    }
+}
+```
+
+### Step 4 — Application class (create OR surgically edit)
+
+- **No existing `Application` subclass**: create `App.kt` (non-Hilt) or `MyApplication.kt` (Hilt) from the examples.
+- **Existing `Application` subclass**: do NOT replace. For Hilt, add `@HiltAndroidApp` if missing. For non-Hilt, insert the Ketoy field declarations + the init lines inside `onCreate()` AFTER `super.onCreate()`. Don't disturb any other init code.
+
+### Step 5 — MainActivity (almost always surgical)
+
+If MainActivity is the Android Studio template boilerplate (single `setContent { Greeting(...) }`), it's safe to replace after diff confirmation. If it contains real user code, do NOT replace — instead add imports + `@Inject lateinit var` declarations + `@AndroidEntryPoint` (Hilt) as surgical edits, then hand the user the `KetoyScreen` snippet to paste inside their existing `setContent { }`. Never silently clobber.
+
+### Step 6 — AndroidManifest.xml (single attribute edit)
+
+Add ONLY the `android:name=".App"` (or `.MyApplication`) attribute to the existing `<application>` tag. Don't replace the `<application>` block — the user has `android:icon`, `android:theme`, `android:label`, `android:allowBackup`, possibly `tools:replace`, network security config, etc. If `android:name` already points at a different Application class → stop and ask.
+
+### Step 7 — Hilt module (Hilt projects only)
+
+If no existing `@Module @InstallIn(SingletonComponent::class)` exists, create `AppHiltModule.kt` + `AppCapabilityProvider.kt` from `examples/hilt-config.kt`.
+
+If the user already has a singleton-scoped Hilt module, append the new `@Binds KetoyCapabilityProvider` + `@Provides` resolvers + config customizer as additive entries inside their existing module rather than introducing a parallel one. Show a diff first.
+
+### Step 8 — Signing keys (optional)
+
+Skip by default. If user opts in, run:
+```bash
+mkdir -p app/keys
+openssl genpkey -algorithm Ed25519 -outform DER -out /tmp/key.der
+tail -c 32 /tmp/key.der > app/keys/sample-private.key
+mkdir -p app/src/main/assets/ketoy/keys
+openssl pkey -in /tmp/key.der -inform DER -pubout -outform DER -out /tmp/pub.der
+tail -c 32 /tmp/pub.der > app/src/main/assets/ketoy/keys/sample-public.key
+echo "**/keys/*-private.key" >> .gitignore
+```
+
+If `openssl` is unavailable, fall back to generating via `KetoyKeystore.generateKeyPair()` at first run (the runtime can do this; document it but don't auto-execute).
+
+### Step 9 — Verify the build
+
+Run `./gradlew :app:assembleDebug`. On failure, fall through to `guides/diagnose-errors.md`.
+
+## What `init` does NOT do
+
+- Generate KBC screens automatically (use `migrate` for that).
+- Register app-specific capabilities (user must add to `AppCapabilityProvider.buildRegistry()`).
+- Set up CDN delivery (that's `KetoyBundleSource.Remote(url)` + your CDN config).
+- Touch existing screens / ViewModels. Migration is explicit and per-file.
+
+## Project structure after init
+
+```
+app/
+├── build.gradle.kts                         (edited: + ketoy block)
+├── ketoy-capabilities.json                  (new)
+├── keys/sample-private.key                  (new, gitignored)
+└── src/main/
+    ├── AndroidManifest.xml                  (edited)
+    ├── assets/ketoy/keys/sample-public.key  (new)
+    ├── java/com/example/app/
+    │   ├── App.kt                           (new)
+    │   ├── MainActivity.kt                  (new or edited)
+    │   ├── ketoyscreens/
+    │   │   ├── Capabilities.kt              (new)
+    │   │   └── HelloKetoyScreen.kt          (new)
+    │   └── di/                              (only if Hilt)
+    │       ├── AppHiltModule.kt
+    │       └── AppCapabilityProvider.kt
+```
+
+After a successful `./gradlew :app:assembleDebug`, the bundle ends up at `app/src/main/assets/ketoy/main.ktx`.