V2

.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "oka",
+  "owner": {
+    "name": "Arenukvern",
+    "url": "https://github.com/Arenukvern/oka"
+  },
+  "plugins": [
+    {
+      "name": "oka",
+      "source": "./plugin",
+      "description": "No-Gradle Flutter Android build system: flutter assemble + direct Android SDK tools for 3-5x faster incremental builds, with plugin packaging, AAB support, and dependency recovery. Bundles agent skills.",
+      "version": "0.1.6",
+      "keywords": [
+        "flutter",
+        "android",
+        "build-system",
+        "gradle",
+        "apk",
+        "aab",
+        "dart",
+        "cli"
+      ],
+      "skills": [
+        "./skills"
+      ]
+    }
+  ]
+}

.cursor/commands/update-faq.md

@@ -0,0 +1,12 @@
+# Update FAQ
+
+After a code change, sync documentation. Stay short & smart.
+
+1. Classify the change:
+   - Architectural / internal trade-off → `docs/guides/design_faq.md` (edit existing Q&A first) or new ADR in `docs/decisions/`
+   - Command / API usage pattern → `docs/guides/build_and_config.md`
+   - Both → both, but never duplicate paragraphs between them
+2. Verify against the actual codebase — document what exists, not wishful APIs.
+3. Remove or supersede Q&As that no longer apply.
+4. Keep answers ≤3 sentences; long examples belong in code/examples.
+5. If a design fork was decided, ensure an accepted ADR exists in `docs/decisions/` and update its `index.md`.

.cursor/rules/faq_usage.mdc

@@ -0,0 +1,23 @@
+---
+description: Router for oka docs — when to read the design FAQ vs build guide vs ADRs
+alwaysApply: true
+---
+
+# FAQ usage — oka
+
+Before answering questions about this repo, route to the right doc:
+
+| Question type | Read |
+|---|---|
+| **Why** is it designed this way? | `docs/guides/design_faq.md`, then `docs/decisions/` |
+| **How** do I run/build/test? | `docs/guides/build_and_config.md` |
+| What does oka own / not own? | `docs/start_here/why_this_repo_matters.md` |
+| Phase status / evidence | `docs/PHASE_CHECKLIST.md` |
+| Behavior of code | The code and tests themselves — docs only link |
+
+Rules:
+
+- Never paraphrase implementation in answers; link to the authoritative file.
+- After changing architecture → add/update a Q&A in `docs/guides/design_faq.md` (or ADR).
+- After changing commands/API usage → update `docs/guides/build_and_config.md`.
+- Design forks require a decision checkpoint + ADR before coding.

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+      # --no-example: example/ is a Flutter app; plain-dart resolution of it
+      # fails (flutter_test is sdk-sourced). Dart >= 3.13 resolves example/
+      # by default. The root suite (ADR conformance + real-pipeline evidence)
+      # skips gracefully without the Flutter/Android SDKs.
+      - run: dart pub get --no-example
+      - run: dart analyze --fatal-infos
+      - name: Root test suite (cross-package conformance)
+        run: dart test
+      - name: Package test suites
+        run: |
+          set -e
+          for pkg in packages/*/; do
+            if [ -d "$pkg/test" ]; then
+              echo "=== $pkg"
+              (cd "$pkg" && dart test)
+            fi
+          done
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+      - name: Contract gates (version sync, docs drift, changelog hygiene)
+        env:
+          OKA_ROOT: ${{ github.workspace }}
+        run: bash tool/contracts/check_contracts.sh
+
+  validate:
+    # pub.dev dry-run for every publishable package (the workspace root is
+    # publish_to: none). Runs on PRs touching packaging.
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+      - run: dart pub get --no-example
+      - name: Publish dry-runs
+        run: |
+          set -e
+          for pkg in packages/*/; do
+            if [ -f "$pkg/pubspec.yaml" ] && ! grep -q "publish_to: none" "$pkg/pubspec.yaml"; then
+              echo "=== $pkg"
+              (cd "$pkg" && dart pub publish --dry-run)
+            fi
+          done

.github/workflows/pub_publish.yml

@@ -0,0 +1,69 @@
+name: Publish to pub.dev
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: pub-dev-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: Assert release tag matches VERSION
+        if: github.event_name == 'push'
+        run: |
+          tag="${{ github.ref_name }}"
+          version="$(tr -d '[:space:]' < VERSION)"
+          tag_version="${tag#v}"
+          if [[ "$tag_version" != "$version" ]]; then
+            echo "FAIL: tag ($tag) does not match VERSION ($version)" >&2
+            exit 1
+          fi
+          bash tool/release/check_version_sync.sh
+
+      # --no-example: example/ is a Flutter app; dart >= 3.13 resolves it by
+      # default, which fails under plain Dart (flutter_test is sdk-sourced).
+      - run: dart pub get --no-example
+
+      # Split packages (ADR-0006) publish in dependency order:
+      # oka_core -> oka_android -> oka (the CLI, packages/oka). Hosted deps
+      # resolve against pub.dev, so the first release trains publish core
+      # before android/cli.
+      - name: Publish oka_core (dry-run preflight)
+        working-directory: packages/oka_core
+        run: dart pub publish --dry-run
+      - name: Publish oka_android (dry-run preflight)
+        working-directory: packages/oka_android
+        run: dart pub publish --dry-run
+      - name: Publish oka (dry-run preflight)
+        working-directory: packages/oka
+        run: dart pub publish --dry-run
+
+      - name: Publish oka_core
+        if: github.event_name == 'push'
+        working-directory: packages/oka_core
+        run: dart pub publish --force
+      - name: Publish oka_android
+        if: github.event_name == 'push'
+        working-directory: packages/oka_android
+        run: dart pub publish --force
+      - name: Publish oka
+        if: github.event_name == 'push'
+        working-directory: packages/oka
+        run: dart pub publish --force

.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release Please
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.github/workflows/release_pr_sync_versions.yml

@@ -0,0 +1,82 @@
+name: Release PR — sync versions
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-pr-sync-versions-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  detect-release-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      is_release_pr: ${{ steps.check.outputs.is_release_pr }}
+    steps:
+      - id: check
+        name: Detect release-please PR
+        run: |
+          title="${{ github.event.pull_request.title }}"
+          head="${{ github.head_ref }}"
+          if [[ "$head" == release-please--* ]] || [[ "$title" == *": release "* ]]; then
+            echo "is_release_pr=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_release_pr=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  auto-sync-versions:
+    needs: detect-release-pr
+    if: needs.detect-release-pr.outputs.is_release_pr == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: Sync release version touchpoints
+        run: bash tool/release/sync_version.sh
+
+      - name: Commit and push if changed
+        run: |
+          if git diff --quiet; then
+            echo "release version touchpoints already in sync"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add \
+            VERSION \
+            pubspec.yaml \
+            .claude-plugin/marketplace.json \
+            plugin/.cursor-plugin/plugin.json \
+            plugin/.codex-plugin/plugin.json \
+            plugin/.claude-plugin/plugin.json
+          git commit -m "chore: sync release version touchpoints"
+          git push origin "HEAD:${{ github.event.pull_request.head.ref }}"
+
+  contract-gates:
+    needs: detect-release-pr
+    if: needs.detect-release-pr.outputs.is_release_pr == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: Run contract gates
+        env:
+          OKA_ROOT: ${{ github.workspace }}
+        run: bash tool/contracts/check_contracts.sh

.gitignore

@@ -10,7 +10,7 @@ pubspec.lock
 *.iml
 *.ipr
 *.iws
-
+rust_wrapper/flutter_assets/
 # Build cache
 .oka_cache/
 
@@ -26,4 +26,8 @@ coverage/
 
 # Local configuration
 *.local.yaml
+example/pubspec_overrides.yaml
+
 
+# Skill Steward benchmark evidence (machine-local)
+.steward/benchmark-summaries/*.json

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.6"
+}

.scratch/discover_app.dart

@@ -0,0 +1,20 @@
+import 'dart:io';
+import 'package:oka/src/build/plugin_discovery.dart';
+
+void main() async {
+  final path = '${Platform.environment['HOME']}/xs/vitamins_quiz_bot/vitamin_shippic_app';
+  final d = PluginDiscovery(verbose: true);
+  final r = await d.discover(path);
+  print('plugins total: ${r.plugins.length}');
+  print('android: ${r.androidPlugins.length}');
+  print('unsupported: ${r.unsupported.length}');
+  for (final p in r.androidPlugins) {
+    print('  ${p.name} class=${p.qualifiedClass} unsupported=${p.unsupportedNative} reason=${p.unsupportedReason ?? "-"}');
+  }
+  try {
+    d.ensureSupported(r, strict: true);
+    print('ensureSupported: OK');
+  } catch (e) {
+    print('ensureSupported: FAIL\n$e');
+  }
+}