@1aboveio/skills 1.0.13 → 1.0.14

package/skills/app-dev/android-foundation/references/setup.md

@@ -1,188 +0,0 @@
-# Android foundation: shell snippets
-
-Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
-functions or traps between calls: step 1 resolves the workspace and writes
-`.cache/android-env.sh`, which also `cd`s into it; every later block starts by sourcing it by
-absolute path, and steps 6–8 run as one command through the bundled `scripts/device-run.sh`.
-
-## 1. Workspace and environment
-
-Workspace precedence is owned by [workspace.md](workspace.md). Do not create a worktree,
-switch branch, fetch or reset when the caller supplied an isolated workspace.
-
-```bash
-set -euo pipefail
-ASSIGNED_WORKSPACE=<assigned-workspace-or-empty>
-CANDIDATE_HEAD=<candidate-head-or-empty>
-WORKSPACE="${ASSIGNED_WORKSPACE:?use the caller assignment or native-start result from workspace.md}"
-test -d "$WORKSPACE"
-git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null
-cd "$WORKSPACE"
-actual_head="$(git rev-parse HEAD)"
-test -z "$CANDIDATE_HEAD" || test "$actual_head" = "$(git rev-parse "$CANDIDATE_HEAD^{commit}")" || {
-  echo "workspace HEAD $actual_head != candidate $CANDIDATE_HEAD; report it; do not switch" >&2
-  exit 1
-}
-mkdir -p .cache
-{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; printf 'export ANDROID_SOURCE_HEAD=%q\n' "$actual_head"; } > .cache/android-env.sh
-cat >> .cache/android-env.sh <<'ENV'
-
-# Repo-specific names, read from the repo's journey wrapper and device harness.
-export APP_FILTER=<android-workspace-package>         # pnpm --filter target
-export DEVICE_PYTHON_DIR=<venv-dir-the-wrapper-reads> # e.g. the default in the wrapper
-export DB_NAME_PREFIX=<db-prefix-the-harness-accepts> # the harness rejects other names
-export DB_URL_VAR=<harness-admin-url-variable>        # e.g. SHARD_ADMIN_URL
-export DB_NAME_VAR=<harness-db-name-variable>         # e.g. SHARD_DB_NAME
-
-# Host paths. Example values are for Apple Silicon with Android Studio.
-export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
-export ANDROID_HOME="$HOME/Library/Android/sdk"
-export ANDROID_SDK_ROOT="$ANDROID_HOME"
-export SOURCE_AVD="$HOME/.android/avd/<installed-avd>.avd"
-export SEED_GRADLE_HOME="$HOME/.gradle"
-export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
-
-# Private caches.
-export GRADLE_USER_HOME="$PWD/.cache/gradle"
-export ANDROID_USER_HOME="$PWD/.cache/android-user"
-export ANDROID_AVD_HOME="$PWD/.cache/android-avd"
-export TMPDIR="$PWD/.cache/tmp"
-export npm_config_cache="$PWD/.cache/npm"
-export npm_config_devdir="$PWD/.cache/node-gyp"
-export PNPM_CONFIG_STORE_DIR="$PWD/.cache/pnpm-store"
-export PNPM_CONFIG_CACHE_DIR="$PWD/.cache/pnpm"
-case "${JAVA_TOOL_OPTIONS:-}" in *java.io.tmpdir*) ;; *)
-  export JAVA_TOOL_OPTIONS="${JAVA_TOOL_OPTIONS:+$JAVA_TOOL_OPTIONS }-Djava.io.tmpdir=$TMPDIR" ;; esac
-
-# Run identifiers: an even console port in 5554-5584 (adb scans only that range),
-# and backend/Metro ports under the names the journey wrapper reads.
-export SETUP_AVD=<new-unique-avd-name>
-export EMULATOR_PORT=<even-port-5554-5584>
-export ANDROID_BACKEND_PORT=<free-port>
-export ANDROID_METRO_PORT=<free-port>
-# Choose the whole-journey deadline; zero disables it and is not suitable for unattended runs.
-export JOURNEY_SECONDS=<positive-journey-timeout-seconds>
-ENV
-source .cache/android-env.sh
-mkdir -p "$TMPDIR" "$npm_config_cache" "$npm_config_devdir" \
-  "$ANDROID_USER_HOME" "$ANDROID_AVD_HOME" .cache/logs
-
-node --version; pnpm --version; java -version; python3 --version
-adb version; "$ANDROID_HOME/emulator/emulator" -version
-# Versions come from the repo's native config and CI preflight.
-for component in platforms/android-<api> build-tools/<build-tools> ndk/<ndk> cmake/<cmake>; do
-  test -d "$ANDROID_HOME/$component" || { echo "Missing SDK: $component" >&2; exit 1; }
-done
-```
-
-The recorded standalone path is reused on retries; verify its lifecycle record names this
-run, branch and base. If an assigned path is missing, is not a Git worktree, or is at another
-revision, stop and report instead of creating another checkout. Never fall back to
-`../<repo>-android-setup`.
-
-If the wrapper reads ports or Python under other names, export aliases in
-`android-env.sh` **as well as** the bundled runner's required names. For example,
-`export APP_METRO_PORT="$ANDROID_METRO_PORT"`; both must select the same port. Adapt
-`DB_URL_VAR` and `DB_NAME_VAR` to the actual harness, not its fallback defaults.
-
-## 2. Install and check
-
-```bash
-source <worktree>/.cache/android-env.sh
-pnpm install --frozen-lockfile --store-dir "$PWD/.cache/pnpm-store"
-pnpm --filter "$APP_FILTER" test
-pnpm --filter "$APP_FILTER" typecheck
-EXPO_PUBLIC_API_URL=https://app.invalid \
-  pnpm --filter "$APP_FILTER" exec expo export --platform android
-python3 -m venv "$DEVICE_PYTHON_DIR"
-"$DEVICE_PYTHON_DIR/bin/python3" -m pip install uiautomator2==<harness-pinned-version>
-```
-
-## 3. Gradle dependencies (pick one)
-
-Seed from a trusted Gradle home:
-
-```bash
-source <worktree>/.cache/android-env.sh
-mkdir -p "$GRADLE_USER_HOME/caches/modules-2/files-2.1"
-rsync -r --ignore-existing \
-  --exclude='*.lock' --exclude='*.lck' --exclude='*.tmp' \
-  "$SEED_GRADLE_HOME/caches/modules-2/files-2.1/" \
-  "$GRADLE_USER_HOME/caches/modules-2/files-2.1/"
-```
-
-Or wire a trusted Maven proxy into the private Gradle home. Append the exports to
-`android-env.sh` so the build in step 4 sees them. Route every repository the build uses,
-JitPack included; a route left unset goes straight upstream.
-
-```bash
-source <worktree>/.cache/android-env.sh
-cat >> "$PWD/.cache/android-env.sh" <<'ENV'
-export GRADLE_MAVEN_REPOSITORY=<proxy>/maven/
-export GRADLE_GOOGLE_REPOSITORY=<proxy>/google-maven/
-export GRADLE_PLUGIN_REPOSITORY=<proxy>/gradle-plugins/
-export GRADLE_JITPACK_REPOSITORY=<proxy>/jitpack/
-ENV
-curl --fail --silent --show-error --max-time 10 <proxy-health-url>
-install -d "$GRADLE_USER_HOME/init.d"
-install -m 0644 <path/to/proxy.init.gradle> "$GRADLE_USER_HOME/init.d/proxy.init.gradle"
-```
-
-## 4. Build
-
-```bash
-source <worktree>/.cache/android-env.sh
-pnpm build:android --max-workers=2 -Dorg.gradle.parallel=false \
-  -Pandroid.builder.sdkDownload=false --console=plain --info \
-  2>&1 | tee .cache/logs/gradle.log
-APK=<path/to/app/build/outputs/apk/debug/app-debug.apk>
-shasum -a 256 "$APK"            # sha256sum on Linux
-unzip -l "$APK" | grep -E 'lib/[^/]+/libreactnative\.so'
-```
-
-## 5. Owned emulator
-
-```bash
-source <worktree>/.cache/android-env.sh
-test -f "$SOURCE_AVD/config.ini"
-test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
-test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
-grep '^image.sysdir.1' "$SOURCE_AVD/config.ini"   # must be an installed, host-compatible image
-mkdir "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
-# Copy without the source's RAM size and give the guest 4 GB (gotchas: adb transport drops).
-grep -Ev '^hw\.ramSize[[:space:]]*=' "$SOURCE_AVD/config.ini" > "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
-echo 'hw.ramSize=4096' >> "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
-printf 'avd.ini.encoding=UTF-8\npath=%s\ntarget=android-<api>\n' \
-  "$ANDROID_AVD_HOME/$SETUP_AVD.avd" > "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
-```
-
-## 6–8. Cleanup, resources and journey: one command
-
-```bash
-source <worktree>/.cache/android-env.sh
-bash <skill-base-dir>/scripts/device-run.sh \
-  --drop node <path/to/device-harness.mjs> drop \
-  -- bash <path/to/foundation-journey-wrapper.sh>
-```
-
-Pass each command as separate words, not as one quoted string. The script:
-
-1. Registers the cleanup trap before anything starts.
-2. Refuses an emulator port outside 5554–5584 and any busy port.
-3. Starts the ADB server, then the emulator (its PID recorded), then `postgres` with
-   `--cidfile` on a random loopback port. Override the image with `POSTGRES_IMAGE`.
-4. Waits for `sys.boot_completed=1` and `pg_isready`. Startup/readiness and cleanup
-   commands have a 30-second limit (`BOUNDED_SECONDS`); exit 124 is terminal. The journey
-   uses the separate `JOURNEY_SECONDS` deadline. Leave time for cleanup after that deadline.
-5. Exports `$DB_URL_VAR`, `$DB_NAME_VAR` (`$DB_NAME_PREFIX` plus a unique suffix) and
-   `ANDROID_EMULATOR_SERIAL`, then runs the journey.
-6. Drops the database, stops the emulator PID (`TERM`, then `KILL` after 10 seconds),
-   removes the container by its CID, and prints `original_stage_exit=<n> cleanup_exit=<n>`.
-   It exits with the journey's status if the journey failed, else the cleanup status.
-
-The runner supervises the journey's process group. Journey children must stay in that
-group; a wrapper that deliberately creates detached services must stop those services
-through its own owner. Send TERM to the launcher and allow its cleanup to finish rather
-than killing it immediately. The generic runner inherits the caller's ADB endpoint and
-does not stop that server: use a verified private endpoint on a shared host and close it
-through the caller's owner. Capture the command's exit status and final summary line.

package/skills/app-dev/android-foundation/references/workspace.md

@@ -1,81 +0,0 @@
-# Android workspace lifecycle
-
-The coordinator or caller owns workspace selection. Resolve it once, before any setup stage,
-and record the result. This reference owns only that lifecycle: private caches, SDK isolation,
-emulator ownership and process cleanup stay in [setup.md](setup.md) and
-[Owned-resource cleanup](../SKILL.md#owned-resource-cleanup).
-
-## Precedence
-
-1. **Assigned workspace and candidate HEAD.** When the caller supplies an isolated workspace
-   and a candidate HEAD, use that workspace and that revision. Do not create a worktree or
-   branch, fetch, reset or switch revisions. Read `git rev-parse HEAD` and report it as the
-   source SHA. If it differs from the candidate HEAD, stop and report the mismatch; never
-   switch the workspace to match.
-2. **Existing owned workspace.** Feature work, fixes and diagnosis reuse the workspace this
-   run or unit already owns, with its private caches, venv and AVD profile. Do not make a
-   second workspace for a retry, a correction or a read-only investigation.
-3. **Standalone fresh setup.** Only when the coordinator reports no usable assignment. Create
-   one managed workspace at
-   `<repo>/.resolve-issues/rush/<run-id>/units/native`. Never create a sibling checkout such
-   as `../<repo>-android-setup`, and never add a second managed path for a retry.
-
-Android and iOS setup in the same run share that one managed workspace; their private cache
-subdirectories and short-lived processes stay separate.
-
-An assigned path that is missing, is not a Git worktree, or is at another revision is not an
-invitation to substitute a fresh checkout: stop and report it. For diagnosis, name the actual
-checkout and HEAD and confirm it contains the failing code; the repository root or another
-checkout may lag the candidate.
-
-## Record before creating
-
-The bundled `scripts/workspace-runtime` is generated from the shared lifecycle
-engine and ships with this skill. Only for standalone fresh setup, run:
-
-```bash
-node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-start --repo <canonical-root> \
-  --platform android --target <verified-target-branch> --base <candidate-SHA> --json
-```
-
-The command records root, owner, exact base, branch, workspace and disposable cache
-paths before creating anything. Use its returned `workspace` as `ASSIGNED_WORKSPACE`
-and `sourceSha` as `CANDIDATE_HEAD` in setup. Keep `run` and `runId`; repeat with
-`--run-id <returned-run-id>` and the same base, target and kind for retries. Never
-invoke it inside a coordinator-assigned unit. It never substitutes `origin/main`
-for the requested source or resets an existing workspace.
-For a package below the root, pass `--native-dir <package-root-containing-android>`.
-Declare other installs or build directories before use with repeated
-`--disposable <exact-workspace-relative-path>`, including package-local `node_modules`.
-
-## Development workspace vs short-lived processes
-
-The workspace, its private caches under `.cache/`, its venv and its AVD profile are
-development resources: retain them across retries and fixes, and keep them private to this
-workspace. Never relocate them to a global cache or share them with a concurrent owner.
-
-Emulators, containers, databases, Metro and ADB endpoints are short-lived: start only those
-the selected checks need and stop only the ones this run started, under the existing
-[cleanup rules](../SKILL.md#owned-resource-cleanup). Never delete a worktree, remove a cache
-with a chmod or `rm` pattern, or use a broad kill to end a process.
-
-A read-only diagnosis does not require a clean environment. Reuse the owned workspace and its
-caches, create only the services the observation needs, and preserve the failed environment's
-evidence. Do not rebuild, reinstall or re-provision merely because the failure is being
-investigated.
-
-## Completion
-
-At the end of the assignment, return the workspace, its cache paths and any retained process
-records to the coordinator for final cleanup. The coordinator owns deletion and retention.
-Register the path with the run's cleanup owner so final cleanup can tell a delivered
-standalone run from unfinished or unpublished work.
-
-- A successful, delivered standalone run must not retain an unbounded cache: mark the
-  workspace and its disposable caches for final cleanup. After stopping its owned
-  services, run `node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-finish --run <run> --json`
-  from the owner checkout. This uses the same cleanup engine as issue workflows.
-- Unfinished or unpublished standalone work keeps the workspace and caches for the next
-  attempt; report what is retained and why.
-
-The parent lifecycle record is authoritative for ownership, retention and final cleanup.