From 7abecfc2c7a44a4527da12b1489f86422bb1776a Mon Sep 17 00:00:00 2001
From: Pascal Garber <pascal@artandcode.studio>
Date: Tue, 22 Sep 2026 10:44:03 +0200
Subject: [PATCH] Android: build:android establishes its own precondition

---
 AGENTS.md                         | 20 ++++++++++++++++++++
 package.json                      |  4 ++--
 packages/app-android/package.json |  1 +
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d1062e60..c4282d91 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,6 +47,26 @@ bundle as exit 1. The residual hole is narrower but not zero — a dispatched co
 neither throws nor sets `process.exitCode` still yields 0 — so keep the chains: they cost
 nothing and they do not depend on the fix holding.
 
+**A `gjsify workspace <name> <script>` entry point has to establish its own precondition.**
+Root `build:android` ran `ns build android` directly: without `@learn6502/core` built first that
+failed loudly (a real session had to run `gjsify workspace @learn6502/core build` by hand to get
+an APK at all), but `app-android` never declared `@learn6502/learn` as a dependency — even though
+`learn`'s `build` script copies its generated `tutorial.ns.xml`/`quick-help.ns.xml` straight into
+`app-android/app/mdx/`. That relationship is a file copy across a workspace boundary, not an
+import, so it is invisible to both module resolution and `--with-dependencies`. The APK still
+built successfully with an empty `app/mdx/` and only crashed on-device opening the tutorial
+(`Builder.load` finding nothing). `build:android`/`start:android` now declare `@learn6502/learn`
+as a real dependency and pass `--with-dependencies` (`-t`/`-d`), which walks a target's declared
+`dependencies` and runs each one's `build` script first — including a plain `^x.y.z` range, not
+only the `workspace:` protocol (fixed upstream in gjsify, see `packages/app-gnome/meson.build`
+for the now-stale workaround it predates). A new entry point is safe from a clean checkout only
+when it either fails loudly on a missing precondition (`start:gnome`/`start:web` do — they run an
+already-built bundle, or resolve imports through a bundler that errors hard on a missing module)
+or establishes it via `--with-dependencies` backed by a real dependency edge for every workspace
+it needs — including one it only reaches through a copied file. `check-workspace-scripts.js`
+cannot check this mechanically: it would have to know whether a given script fails loud or ships
+silently, which is a design decision, not something to guess.
+
 ## Releases
 
 A tag produces artifacts. Until 0.7.0 it produced none — Flathub was the only way
diff --git a/package.json b/package.json
index 157c64ad..e444fb09 100644
--- a/package.json
+++ b/package.json
@@ -446,7 +446,7 @@
     "build": "gjsify foreach -v --topological-dev build",
     "build:gnome:flatpak": "gjsify flatpak build eu.jumplink.Learn6502.json --install --repo repo --bundle eu.jumplink.Learn6502.flatpak --tarball eu.jumplink.Learn6502.tar.gz --install-deps-from flathub",
     "build:gnome:meson": "meson compile -C _build",
-    "build:android": "gjsify workspace @learn6502/app-android build",
+    "build:android": "gjsify workspace @learn6502/app-android build --with-dependencies",
     "check": "gjsify foreach -v -t check",
     "check:flatpak:repo": "flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo",
     "check:format": "gjsify format --check",
@@ -459,7 +459,7 @@
     "start:gnome": "gjsify workspace @learn6502/app-gnome start",
     "start:gnome:flatpak": "flatpak run eu.jumplink.Learn6502",
     "start:web": "gjsify workspace @learn6502/app-web start",
-    "start:android": "gjsify workspace @learn6502/app-android start",
+    "start:android": "gjsify workspace @learn6502/app-android build --with-dependencies && gjsify workspace @learn6502/app-android start",
     "clear": "gjsify foreach -v -p clear && gjsify run _clear",
     "_clear": "rm -rf builddir build-dir .flatpak-builder flatpak-build repo eu.jumplink.Learn6502.tar.gz",
     "format": "gjsify format --write",
diff --git a/packages/app-android/package.json b/packages/app-android/package.json
index 0f2e4e6c..3580365c 100644
--- a/packages/app-android/package.json
+++ b/packages/app-android/package.json
@@ -17,6 +17,7 @@
     "@gjsify/adwaita-nativescript": "^0.51.1",
     "@learn6502/core": "^0.8.0",
     "@learn6502/common-ui": "^0.8.0",
+    "@learn6502/learn": "^0.8.0",
     "@nativescript/core": "9.1.0-alpha.11",
     "@nativescript/localize": "^5.2.0",
     "@nativescript/tailwind": "^4.0.9",