refactor(build): migrate to gulp (#2)

Author: LemonNekoGH

.github/workflows/platform-integration-android.yml

@@ -66,8 +66,11 @@ jobs:
       - name: Install pnpm dependencies
         run: mise x -- corepack pnpm install --frozen-lockfile
 
+      - name: Build Android AAR
+        run: mise x -- corepack pnpm run build:android-aar
+
       - name: Build integration APK
-        run: mise x -- bash -c 'GODOT_BIN="${GODOT:-godot}" scripts/build_integration_android.sh'
+        run: mise x -- corepack pnpm run build:integration-android
 
       - name: Enable KVM
         run: |

.github/workflows/platform-integration-ios.yml

@@ -43,7 +43,7 @@ jobs:
         uses: maxim-lobanov/setup-xcode@v1
         with:
           xcode-version: latest-stable
-      
+
       - name: Install XcodeGen, Task, SCons and MoltenVK
         run: brew install xcodegen task scons molten-vk
 
@@ -52,12 +52,12 @@ jobs:
           curl -LO https://github.com/godotengine/godot/archive/refs/tags/4.6.2-stable.tar.gz
           tar -xzf 4.6.2-stable.tar.gz
           mv godot-4.6.2-stable godot
-      
+
           cd godot
-      
+
           MOLTENVK_PATH="$(brew --prefix molten-vk)"
           echo "Using MoltenVK from: ${MOLTENVK_PATH}"
-      
+
           scons platform=macos target=editor \
             vulkan_sdk_path="${MOLTENVK_PATH}" \
             core/version_generated.gen.h \
@@ -81,8 +81,11 @@ jobs:
       - name: Install pnpm dependencies
         run: mise x -- corepack pnpm install --frozen-lockfile
 
+      - name: Build iOS XCFramework
+        run: mise x -- corepack pnpm run build:ios-xcframework
+
       - name: Build integration App
-        run: mise x -- bash -c 'GODOT_BIN="${GODOT:-godot}" scripts/build_integration_ios.sh'
+        run: mise x -- corepack pnpm run build:integration-ios
 
       - name: Start iOS Simulator
         run: |
@@ -96,7 +99,7 @@ jobs:
       - name: Run integration tests
         run: |
           xcrun simctl install $SIMULATOR_ID dist/integration/ios_debug.app
-          
+
           scripts/run_integration_ios_test.sh ipc_round_trip_probe
           scripts/run_integration_ios_test.sh webview_lifecycle_probe
           scripts/run_integration_ios_test.sh res_asset_loading_probe

.gitignore

@@ -7,10 +7,10 @@
 node_modules/
 dist/
 build/
+godot/
 *.apk
 *.aab
 *.aar
-!packages/kirie/addon/addons/kirie/libraries/android/Kirie-debug.aar
 *.xcframework
 
 .build_version

AGENTS.md

@@ -33,8 +33,10 @@ higher-level work.
   the first runnable manual integration target
 - `tests/integration`
   exported-app platform bridge regression target
+- `gulpfile.ts`
+  native artifact and integration export orchestration
 - `scripts`
-  local build and run helpers for Android and iOS validation
+  local run helpers for Android and iOS validation
 - `.codex/skills`
   repo-local Codex skills for project maintenance workflows
 - `docs`
@@ -84,22 +86,19 @@ is a standard Godot plugin:
 
 - users consume `addons/kirie`
 - Android binaries are exported through `EditorExportPlugin`
-- during bring-up, local `.aar` files under the addon are acceptable because the
-  current Android bridge does not require Kirie-owned Maven-delivered runtime
-  dependencies
 - Maven-based Android delivery can be revisited if Kirie gains Android
   dependencies that need Gradle metadata or transitive resolution
 
 When producing a downloadable addon tree, ensure Android `.aar` files are real
-files in the generated output, not repository-local symlinks into Gradle build
+files in the staged output, not repository-local symlinks into Gradle build
 directories.
 
 ## iOS Packaging Direction
 
 For the current milestone, iOS should be owned by the standard addon tree:
 
 - users consume `addons/kirie`
-- `Kirie.xcframework` belongs under `addons/kirie/ios` in produced addon trees
+- `Kirie.xcframework` belongs under `addons/kirie/ios` in staged addon trees
 - iOS native pieces are injected through `EditorExportPlugin` Apple export hooks
 - do not reintroduce `res://ios/plugins` or `.gdip` shims unless the export hook
   approach fails and the user explicitly chooses that fallback
@@ -132,6 +131,20 @@ For the current milestone, iOS should be owned by the standard addon tree:
   tool workaround.
 - Keep Gradle wrapper and Xcode usage as-is; mise only provides the Java runtime
   and command-line tools around them.
+- Start command invocations with the fewest necessary flags and options. Add
+  extra flags only after the project or user has a concrete need for them.
+- Native artifact orchestration lives in `gulpfile.ts`. Use
+  `mise x -- corepack pnpm run build:android-aar`,
+  `mise x -- corepack pnpm run build:ios-xcframework`, or
+  `mise x -- corepack pnpm run build:native-artifacts` instead of adding new
+  shell-only orchestration for the same artifact path.
+- Integration export orchestration also lives in `gulpfile.ts`. Use
+  `mise x -- corepack pnpm run build:integration-android` or
+  `mise x -- corepack pnpm run build:integration-ios` instead of adding new
+  integration build shell scripts.
+- Keep `gulpfile.ts` executable by Node's built-in TypeScript type stripping:
+  use erasable TypeScript syntax only and do not add `ts-node`, `tsx`, or other
+  TypeScript runtime loaders unless a real non-erasable TypeScript need appears.
 
 ## Engineering Rules
 
@@ -164,6 +177,9 @@ configured yet.
 - Do not wrap platform APIs with thin pass-through helpers unless the wrapper
   actually stabilizes the Godot-facing API, hides a platform difference, or
   creates a meaningful test seam.
+- Do not add extra guard code only to beautify errors. Prefer the underlying
+  tool, runtime, or filesystem error unless the guard changes behavior or makes
+  a likely failure materially easier to debug.
 - Prefer keeping logic close to the module that owns it instead of extracting it
   into cross-cutting helpers too early.
 - Add configuration, extension points, and generic options only when they are
@@ -199,11 +215,12 @@ configured yet.
   `mise x -- corepack pnpm run format:swift`.
 - When changing Android bridge code, validate the Godot-to-native-to-web path as
   soon as practical.
+- After changing Android native code under `packages/kirie/native/android`,
+  run `mise x -- corepack pnpm run build:android-aar` before exported-app tests.
 - When changing iOS bridge code, validate the Godot-to-native-to-web path as
   soon as practical.
 - After changing iOS native code under `packages/kirie/native/ios`, always run
-  `scripts/build_kirie_ios.sh` so `addons/kirie/ios/Kirie.xcframework` is
-  refreshed before any device testing.
+  `mise x -- corepack pnpm run build:ios-xcframework` before device testing.
 - When changing the IPC shape, make sure at least one real request/response
   round-trip remains covered by the example or integration tests.
 - When changing `KirieClient`, compile it against the Godot .NET SDK. A platform
@@ -234,11 +251,12 @@ configured yet.
 ### Binary artifacts
 
 - Avoid committing build outputs by default.
-- Do not commit `.aar`, `.xcframework`, exported app bundles, or similar binary
-  artifacts unless the repository intentionally adopts them as source-distributed
-  plugin assets.
-- If the repository starts tracking a binary artifact class intentionally, add
-  the rule explicitly here.
+- `.aar`, `.xcframework`, exported app bundles, and similar binaries are release
+  staging artifacts in this repository. Generate them into the addon tree or
+  release staging tree when needed, but do not commit them.
+- If the repository intentionally adopts a binary artifact class as
+  source-distributed plugin assets later, add the exception explicitly here and
+  update `.gitignore` in the same change.
 
 ### Logging and lifecycle
 
@@ -261,5 +279,3 @@ infrastructure.
   not exist yet.
 - Richer app-level adapters or invocation APIs above `@gd-kirie/ipc` are not
   implemented yet.
-- Source tracking policy is not finalized yet for generated binary artifacts
-  such as local `.aar` files and `.xcframework` bundles.

README.md

@@ -24,7 +24,8 @@ example, and regression-test areas:
 - `packages/ipc`: a thin browser-side transport wrapper for Kirie WebView pages
 - `examples/basic-ipc`: the first runnable manual integration example
 - `tests/integration`: exported-app platform integration tests
-- `scripts`: local build and run helpers for native validation
+- `gulpfile.ts`: native artifact and integration export orchestration
+- `scripts`: local run helpers for native validation
 - `docs`: project notes and design decisions
   - `docs/dreams`: exploratory notes for ideas outside the current milestone
 

docs/platform-integration-tests.md

@@ -162,10 +162,16 @@ bridge assertion.
 
 ## Android Local Flow
 
+Build the staged Android addon AAR first:
+
+```bash
+mise x -- corepack pnpm run build:android-aar
+```
+
 Build the test APK:
 
 ```bash
-scripts/build_integration_android.sh
+mise x -- corepack pnpm run build:integration-android
 ```
 
 Install it once:
@@ -212,18 +218,34 @@ Tests are isolated by app session:
 This avoids residual WebView, JavaScript, singleton, signal, and cache state
 without exporting a separate APK for every test.
 
-## CI Direction
+## iOS Local Flow
+
+Build the staged iOS addon XCFramework first:
+
+```bash
+mise x -- corepack pnpm run build:ios-xcframework
+```
+
+Build the simulator app:
 
-The intended GitHub Actions shape is:
+```bash
+mise x -- corepack pnpm run build:integration-ios
+```
+
+Install and run tests with the simulator helper:
+
+```bash
+scripts/run_integration_ios_test.sh ipc_round_trip_probe
+```
+
+The iOS XCFramework and simulator app tasks expect the Godot source checkout at
+repo-root `godot/`.
+
+## CI Direction
 
-- set up Node and Java with `jdx/mise-action`
-- set up Godot and export templates with `chickensoft-games/setup-godot`
-- install pnpm dependencies
-- build the Android AAR
-- export `tests/integration` as an Android APK
-- start an emulator with `reactivecircus/android-emulator-runner`
-- install the APK once
-- run each test through `scripts/run_integration_android_test.sh`
+The CI flows live in `.github/workflows/platform-integration-android.yml` and
+`.github/workflows/platform-integration-ios.yml`. They build the native staging
+artifacts before exporting the integration project.
 
 CI should reuse the same marker contract and app-session isolation used
 locally.

docs/references.md

@@ -78,6 +78,13 @@ packaging, or platform WebView bridge details.
 
 ## JavaScript packaging
 
+- [Node.js TypeScript support](https://nodejs.org/api/typescript.html)
+  Reference for Node's built-in TypeScript type stripping and erasable syntax
+  constraints used by the repository `gulpfile.ts`.
+- [Gulp creating tasks](https://gulpjs.com/docs/en/getting-started/creating-tasks/)
+  Reference for exported Gulp task functions and task composition.
+- [Execa](https://github.com/sindresorhus/execa)
+  Reference for programmatic process execution from the repository task runner.
 - [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
   Reference for publishing npm packages from GitHub Actions through OIDC instead
   of long-lived npm tokens.
@@ -102,3 +109,5 @@ packaging, or platform WebView bridge details.
   support, C# signals, and .NET reflection or AOT documentation.
 - When changing npm package publishing, start with npm trusted publishing,
   GitHub Actions OIDC, bumpp, and pnpm publish behavior.
+- When changing native artifact orchestration, start with Node.js TypeScript
+  support and the Gulp task composition references.