ketoy-dev 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2024–2026 Aditya Shinde (developerchunk) — KetoyVM contributors.

package/README.md

@@ -0,0 +1,101 @@
+# ketoy
+
+AI-powered command-line agent for [Ketoy](https://ketoy.dev) — scaffold a Ketoy-enabled Android project, write `@KetoyComposable` screens, migrate existing Compose UI to `.ktx` bytecode bundles, diagnose compiler-plugin errors, and build / inspect bundles.
+
+Powered by the [Vercel AI SDK](https://sdk.vercel.ai) — bring your own API key from **Anthropic, OpenAI, Google Gemini, Mistral, Groq, xAI, OpenRouter, or local Ollama**. Source code never leaves your machine except as part of explicit prompts you send to the provider you chose.
+
+```
+npm install -g ketoy-dev
+ketoy auth anthropic     # paste your API key (never logged, stored 0600 in ~/.ketoy-cli)
+ketoy init               # add Ketoy to your Android project (surgical edits)
+ketoy chat               # open an AI session in the project root
+```
+
+> The npm package is **`ketoy-dev`** (the bare `ketoy` name is blocked by npm's similarity heuristic against unrelated existing packages). The installed binary is still `ketoy`.
+
+---
+
+## Commands
+
+```
+ketoy init [--install-screen | --no-install-screen] [--hilt | --no-hilt] [-y] [--dry-run]
+ketoy chat [prompt...]                                    # interactive agent
+ketoy migrate <file>...                                   # AI-driven per-file Compose → KBC migration
+ketoy doctor [task]                                       # run a Gradle task and diagnose any errors
+ketoy build [--variant bundle|debug|release]              # `./gradlew :app:ketoyBundle --rerun-tasks`
+ketoy analyze <path.ktx> [--manifest] [--strings] [--json]
+ketoy config list|get|set
+ketoy auth [provider] [--remove] [--list]
+ketoy version
+```
+
+Every command runs in the current working directory. `ketoy init` only writes files when invoked from an Android project root (one containing `settings.gradle.kts` and `app/build.gradle.kts`).
+
+## Provider setup
+
+```
+ketoy auth anthropic              # set ANTHROPIC API key
+ketoy auth openai                 # OpenAI
+ketoy auth google                 # Google Gemini
+ketoy auth mistral
+ketoy auth groq
+ketoy auth xai
+ketoy auth openrouter             # one key, 200+ models
+ketoy auth ollama                 # local — no API key, just a base URL
+ketoy auth --list                 # see what's configured (redacted)
+```
+
+Then pick a default model:
+
+```
+ketoy config set model anthropic:claude-sonnet-4-5
+ketoy config set model openai:gpt-4o
+ketoy config set model google:gemini-2.0-flash-exp
+ketoy config set model openrouter:meta-llama/llama-3.1-405b-instruct
+```
+
+Or override per-command with `--model <provider>:<name>`.
+
+Credentials are stored at `~/.ketoy-cli/config.json` (mode `0600`). The CLI refuses to print them — `ketoy config get apiKeys` is intentionally blocked. Use `ketoy auth --list` for a redacted view.
+
+## Safety guarantees
+
+- **No file is rewritten in full.** Edits to `build.gradle.kts`, `AndroidManifest.xml`, `MainActivity.kt`, and `Application` classes are surgical — single-line additions or block appends at well-identified anchors. Existing dependencies, signing configs, themes, ProGuard rules are never touched.
+- **Diff-and-confirm** on every edit touching a high-risk file. The agent's `edit_file` tool always shows a unified diff and prompts before applying.
+- **Idempotent** — re-running `ketoy init` on an already-configured project is a no-op.
+- **Allowlisted bash with hard refusal of compound commands** for auto-approval. `cat && rm -rf /` looks like `cat` to a naive checker; the CLI refuses to auto-approve any command containing shell metacharacters (`;`, `&&`, `||`, `|`, backticks, `$(…)`, redirects).
+- **No telemetry.** No analytics, no usage reporting, no remote logging. The CLI talks directly to the provider you configured.
+
+## What `ketoy init` does
+
+1. Detects: `namespace`, `applicationId`, `minSdk`, Hilt usage, existing `Application` class, existing `MainActivity`.
+2. **Hilt opt-in** — non-Hilt setup is the default. If you opt in to Hilt, init aborts with a pointer to `ketoy chat`, where the agent handles Hilt configuration against your existing modules.
+3. **KetoyScreen install opt-in** — `--install-screen` (default for fresh AS projects) wraps `MainActivity`'s `setContent` body with `KetoyScreen { /* native fallback */ }` inside your app theme. `--no-install-screen` leaves `MainActivity.kt` untouched and prints a manual integration snippet.
+4. Plans a list of surgical edits + new file creations; shows the plan, asks to confirm.
+5. Applies the non-Hilt setup:
+   - Inserts `id("dev.ketoy.compiler") version "0.3.4-alpha"` into `app/build.gradle.kts`'s plugins block
+   - Appends `// Ketoy 0.3.4-alpha` dependencies (BOM + runtime + annotations + capabilities-core + capabilities-navigation + adapters-material3)
+   - Appends the `ketoy { exportFromAppModule = true; bundleId = "main"; bundleVariant = "release"; … }` block
+   - Sets `android:name=".MyApplication"` on `<application>` in `AndroidManifest.xml` (only if no existing Application class)
+   - Creates `MyApplication.kt` with the **full bootstrap**: `KetoyConfig` (sig verification, font / drawable / icon resolvers), `CapabilityRegistry`, `KetoyRuntime`, `registerGeneratedAdapters` / `registerGeneratedConstructors`, `KetoyBundleLoader`
+   - Creates / surgically wraps `MainActivity.kt` — `<YourAppTheme> { CompositionLocalProvider(LocalKetoyRuntime / LocalKetoyBundleLoader) { KetoyScreen(entryPoint = "HelloKetoyScreen") { /* native fallback */ } } }`
+   - Creates `HelloKetoyScreen.kt` (sample `@KetoyEntryPoint @KetoyComposable`)
+   - Creates `app/ketoy-capabilities.json` (empty)
+   - Appends `**/keys/*-private.key` to `.gitignore`
+6. Saves project state to `.ketoy/state.json` so future commands know the layout.
+
+Then: `./gradlew :app:assembleDebug`, install, and you have a real KBC bundle running inside your APK.
+
+### Alpha-period version pinning
+
+Ketoy 0.3.x's compiler plugin is built against a specific Kotlin / AGP / Compose BOM combination. `ketoy init` pins your `gradle/libs.versions.toml` to the required versions (Kotlin 2.0.21, AGP 8.13.2, Compose BOM 2024.10.00, plus matched AndroidX libs). These pins are temporary — ADR-0004 (Ketoy ships its own embedded Kotlin compiler) removes them.
+
+## Requirements
+
+- **Node.js ≥ 20** (top-level await + modern fetch)
+- **Android Gradle Plugin 8.x** + **Kotlin 2.0.21** + **JDK 17** (auto-pinned during `ketoy init`)
+- **minSdk ≥ 26**
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **ketoy.dev@gmail.com** with the subject line `[SECURITY] ketoy-cli`. Please do not open a public issue for security reports. Expect an initial response within 72 hours.
+
+## Threat model
+
+The CLI executes locally on a developer machine, reads / writes files in the current working directory, runs `./gradlew` build tasks, and forwards prompts + file content the user explicitly hands it to a language-model provider chosen by the user. It does not:
+
+- Open inbound network sockets.
+- Run anything as root or modify system-wide state.
+- Collect telemetry / analytics / crash reports.
+- Read or transmit content outside the project root (every agent file tool refuses paths that escape the working directory).
+
+## Hardening already in place
+
+- **API keys** are stored at `~/.ketoy-cli/config.json` with mode `0600` and dir mode `0700`. Printing them via `ketoy config get apiKeys` is refused; the only read path is `ketoy auth --list`, which prints `…last4` only.
+- **Prototype pollution** through `ketoy config set` is blocked at the dotted-key validation step (`__proto__`, `prototype`, `constructor` are refused).
+- **Path traversal** through agent tools (`read_file`, `write_file`, `edit_file`, `analyze_ktx`) is blocked by absolute-path containment against the resolved project root — not by string-prefix checks that can be defeated on Windows.
+- **Shell auto-approval** for the agent's `bash` tool is gated by an allowlist of read-only / build commands AND a hard refusal for any command containing shell metacharacters (`;`, `&&`, `||`, `|`, backticks, `$()`, redirects). `cat foo && rm -rf /` requires explicit user confirmation, never auto-approves.
+- **Surgical edits only** for all high-risk files (`build.gradle.kts`, `AndroidManifest.xml`, `MainActivity.kt`, `Application` classes). Whole-file rewrites are never produced. Every high-risk edit shows a unified diff and prompts the user.
+
+## Known transitive advisories
+
+`npm audit` against `ketoy` currently reports three moderate findings inherited from upstream dependencies. None are exploitable through the CLI's actual usage; details below. We track upstream fixes and bump as they ship.
+
+| Advisory | Source | Why not exploitable here |
+| --- | --- | --- |
+| GHSA-rwvc-j5jr-mgvh (`ai` <= 5.0.51 — file upload filetype bypass) | Vercel AI SDK | The CLI never uploads user-supplied files. Tool results sent to the model are JSON / text only. |
+| GHSA-gh4j-gqv2-49f6 (`fast-xml-parser` < 5.7.0 — XMLBuilder injection) | `fast-xml-parser` | The CLI only **parses** XML (`AndroidManifest.xml` inspection). The vulnerable `XMLBuilder` path is never reached. |
+| GHSA-33vc-wfww-vjfv (`jsondiffpatch` < 0.7.2 — HtmlFormatter XSS) | Transitive of `ai` | The CLI runs in a terminal, not a browser. The HTML diff formatter is never invoked. |
+
+Bumping `ai` to v6 / `fast-xml-parser` to v5 require breaking-change migrations. The bumps are tracked for the next minor release.