diff --git a/.github/workflows/agents-check.yml b/.github/workflows/agents-check.yml index a919261e4c..f0e44f488e 100644 --- a/.github/workflows/agents-check.yml +++ b/.github/workflows/agents-check.yml @@ -34,6 +34,8 @@ jobs: python-version: '3.11' cache: pip cache-dependency-path: devtools/code_health/requirements.txt + - name: Offline development launcher tests + run: python3 -m unittest discover -s lab/scripts -p test_start_dev.py -v - name: Code health linter self-tests run: | python -m pip install -r devtools/code_health/requirements.txt diff --git a/lab/DEV_INSTANCE.md b/lab/DEV_INSTANCE.md new file mode 100644 index 0000000000..fc17b31f4b --- /dev/null +++ b/lab/DEV_INSTANCE.md @@ -0,0 +1,157 @@ +# Start a development instance + +Once a slot is configured, run this from any directory: + +```sh +python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py A +``` + +Use `B` for the other console. Keep the terminal open. Quit the GUI normally to +release its console lock; Ctrl-C requests termination and waits for the child +before releasing ownership. This opens the application, not an automation program. +Existing saved panels may reconnect their assigned devices under #237's guards. + +To see the resolved configuration without fetching, locking, building or launching: + +```sh +python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py A --plan +``` + +The launcher lives on the `agents` tools branch; it orchestrates a separate code +checkout. Do not merge `agents` into a code branch. Before this tools PR merges, +use the script from its review worktree instead of the path above. + +## Configure once + +1. Use a **dedicated** code worktree and local or remote `lab/...` integration branch for + each slot. Do not point at an agent's active checkout. The integration branch + merges `lab/main`, the device-ownership guard (#237), and the feature under + test. Upstream-bound feature branches never merge lab tooling. + + For example, to prepare a new Max Lair development branch (review/resolve any + merge conflict normally before continuing): + + ```sh + git -C ~/Projects/Arduino-Source fetch origin + git -C ~/Projects/Arduino-Source worktree add -b lab/dev-maxlair ~/Projects/wt/dev-maxlair origin/lab/main + git -C ~/Projects/wt/dev-maxlair merge origin/lab/device-ownership + git -C ~/Projects/wt/dev-maxlair merge origin/swsh/maxlair-boss-tests + ``` + + The launcher switches to the configured branch and fetches origin. If a matching + remote lab branch exists, it fast-forwards; a local integration branch needs + no publication. It preserves local integration commits. + It never stashes, resets, rebases, resolves conflicts, merges feature changes, + commits or pushes. It refuses dirty worktrees, branches checked out elsewhere, + divergent updates, missing lab-main ancestry, and missing device guards. + Refresh integration merges yourself when parents change. The guard check is + pinned to #237's known runtime-adapter revision `45afc7eb048b638f34a62e79c8bbf7d65a377e1e`; + a future history that removes this ancestry needs a reviewed pin update. + +2. Prepare `lab-A` / `lab-B` profiles using [#236's preference-only seeding](https://github.com/dayfine/Arduino-Source/blob/lab/profile-preparation/devtools/lab/INSTANCE_PREPARATION.md). + Review their `lab-devices.json` using [#237's device ownership instructions](https://github.com/dayfine/Arduino-Source/blob/lab/device-ownership/devtools/lab/DEVICE_OWNERSHIP.md). + Empty allowlists permit GUI setup without device opens. The launcher does not + copy default settings, discover/approve device identities, or configure panels. + Confirm physical A/B assignments before enabling devices. Older unguarded + applications must remain disconnected from those devices. + +3. Keep the existing persistent signing certificate and normal Qt/OpenCV/CMake + setup. See [local signing](../pokemon_sv/lab/MACOS_LOCAL_SIGNING.md). + No certificate, permissions or TCC changes are made by this launcher. A fresh + build needs the normal development dependencies (including Qt SerialPort), + SDK/OpenCV paths and Packages resources. Configure any machine-specific cache + values in `cmake_args`. Existing build directories must already match both the + selected source and profile; an unbound/default build is refused rather than + repurposed. Use separate build directories outside each source checkout. + +4. Save `~/.config/pokemonautomation/dev-labs.json`. Paths below are examples; + choose your dedicated directories. A one-slot file is valid: omit B until it + has been prepared. + + ```json + { + "schema": 1, + "slots": { + "A": { + "worktree": "~/Projects/wt/dev-maxlair", + "branch": "lab/dev-maxlair", + "build_dir": "~/Projects/dev-builds/slot-A", + "stage_root": "~/Projects/dev-deployments/slot-A", + "bundle_id": "com.dayfine.pokemonautomation.labA", + "signing_identity": "PokemonAutomation Local Development", + "cmake_args": ["-DCMAKE_BUILD_TYPE=RelWithDebInfo"] + }, + "B": { + "worktree": "~/Projects/wt/dev-bdsp", + "branch": "lab/dev-bdsp", + "build_dir": "~/Projects/dev-builds/slot-B", + "stage_root": "~/Projects/dev-deployments/slot-B", + "bundle_id": "com.dayfine.pokemonautomation.labB", + "signing_identity": "PokemonAutomation Local Development", + "cmake_args": ["-DCMAKE_BUILD_TYPE=RelWithDebInfo"] + } + } + } + ``` + + The console selects the profile (`A` → `lab-A`, `B` → `lab-B`). Profiles, + bundle IDs and directories cannot be shared between configured slots. + `cmake_args` accepts cache `-DKEY=VALUE` entries, not arbitrary shell commands + or alternate CMake source/preset/script/profile overrides. + +Optional shell convenience after setup: + +```sh +alias dev-a='python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py A' +alias dev-b='python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py B' +``` + +## What the command does + +1. Acquires the existing console lock protocol at `~/.lab/locks/A` (or B), then + the launcher-wide build lock. A busy console/build fails immediately. +2. Checks the worktree is clean; fetches origin, switches the named lab branch, + and fast-forwards it when a matching remote exists; checks its lab/device-guard ancestry and profile policy. +3. Configures the profile-bound build and builds with **four workers**. Configure + and build output remains in the terminal. It refuses source changes during + building and a linked receipt from a different source revision. +4. Calls the existing `lab_instance.py stage`/`verify` tools to create and sign + a new deployment. Copies the build's `Resources`, `Firmware` and `Scripts` + beside the app, matching macOS `Main.cpp`'s working-directory behavior. Missing + runtime directories prevent launch. Existing deployments are never overwritten. +5. Releases the build lock, then starts the actual executable as a supervised + foreground child with `--profile lab-A`/`lab-B`. The console lock remains + held until the GUI process exits. The app's native profile/device leases are + a separate layer and enforce ownership before actual device opens. + +The console lock interoperates with `lab/control/lablock.sh`, `lc.sh` and CFR +helpers. It is not a replacement for the native device leases. Other local build +commands do not participate in the build mutex: do not run them concurrently. +Another console can start its build after this launcher finishes staging, while +this GUI remains open. The launcher does not select a program, press Start, +stop another instance, reset a console or modify saves. + +Each run stages a new immutable directory under `stage_root`, with the source +revision in its name and the deployment manifest alongside it. Bundle identity +and certificate remain stable, but paths change; this version does not promise +macOS permission prompts will never recur. Old deployments are retained for +inspection; remove unused ones only after confirming their app has exited. + +If a source-only change did not relink and its receipt is stale, relink through +the normal CMake build (for example, a deliberate clean rebuild) before retrying. +Do not edit a receipt to make it pass. If a console lock remains after an abrupt +launcher crash, inspect it with the existing `lablock.sh -c A status`; the launcher +never deletes somebody else's lock or automatically evicts an existing owner. + +## Offline verification + +```sh +python3 -m unittest discover -s lab/scripts -p test_start_dev.py -v +``` + +Tests cover config/slot isolation, real temporary Git checkout and fast-forward, +clean-source checks, console/build exclusion, compatibility with the existing +shell lock, failure ordering, runtime data staging and interruption with delayed +child teardown. They use temporary repositories/processes and injected build/ +signing/GUI operations. They do not build the app, launch a live profile, sign +with the real certificate or validate physical capture/controller behavior. diff --git a/lab/LAB_BUILDS.md b/lab/LAB_BUILDS.md index eb47c76e64..bcc8fee71e 100644 --- a/lab/LAB_BUILDS.md +++ b/lab/LAB_BUILDS.md @@ -1,5 +1,7 @@ # Lab builds base on `lab/main` +For a human one-command build and launch, see [Start a development instance](DEV_INSTANCE.md). + Every lab build (BDSP AutoStory on console B, FRLG nav on console A, any future lab) is built from a branch that merges `lab/main`. Lab-only tooling lives there, not in fork `main`. diff --git a/lab/scripts/start_dev.py b/lab/scripts/start_dev.py new file mode 100644 index 0000000000..e2985debf0 --- /dev/null +++ b/lab/scripts/start_dev.py @@ -0,0 +1,301 @@ +#!/usr/bin/env python3 +"""Build and run one macOS development lab, holding its console lock until exit. + +Configure once using lab/DEV_INSTANCE.md, then from any directory: + python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py A + python3 ~/Projects/Arduino-Source-agents/lab/scripts/start_dev.py B --plan + python3 lab/scripts/start_dev.py A --config /path/to/dev-labs.json + +This opens the GUI, not an automation program. The selected code branch must +include the profile-preparation and native device-ownership guards (#236/#237). +""" + +import argparse +from contextlib import contextmanager +from datetime import datetime +import fcntl +import json +import os +from pathlib import Path +import re +import secrets +import shlex +import shutil +import signal +import subprocess +import sys +import time + + +DEFAULT_CONFIG = Path.home() / '.config/pokemonautomation/dev-labs.json' +# A known revision containing the actual runtime adapters, not just a package flag. +DEVICE_GUARD_REVISION = '45afc7eb048b638f34a62e79c8bbf7d65a377e1e' + + +def load_config(path, console): + """Resolve a reviewed slot configuration; never derive device assignments.""" + data = json.loads(Path(path).expanduser().read_text()) + if set(data) != {'schema', 'slots'} or data['schema'] != 1: + raise ValueError('Expected schema 1 and slots in the configuration.') + slots = data['slots'] + if not isinstance(slots, dict) or not slots or set(slots) - {'A', 'B'}: + raise ValueError('Configure only console slots A and B.') + required = {'worktree', 'branch', 'build_dir', 'stage_root', 'bundle_id', 'signing_identity'} + all_paths = [] + identifiers = set() + for name, raw in slots.items(): + if not isinstance(raw, dict) or not required <= raw.keys() or raw.keys() - required - {'cmake_args'}: + raise ValueError('Each slot requires worktree, branch, build_dir, stage_root, bundle_id and signing_identity.') + if not all(isinstance(raw[key], str) and raw[key].strip() for key in required): + raise ValueError('Slot values must be nonempty strings.') + if not re.fullmatch(r'lab/[A-Za-z0-9_./-]+', raw['branch']) or '..' in raw['branch']: + raise ValueError('Select a lab/... integration branch, not a feature PR branch.') + if not re.fullmatch(r'com\.dayfine\.pokemonautomation\.lab[A-Za-z0-9_-]+', raw['bundle_id']): + raise ValueError('Use a dedicated com.dayfine.pokemonautomation.lab... bundle ID.') + if raw['bundle_id'] in identifiers or raw['signing_identity'] == '-': + raise ValueError('Bundle IDs must be distinct and signing must use a persistent certificate.') + identifiers.add(raw['bundle_id']) + arguments = raw.get('cmake_args', []) + if not isinstance(arguments, list) or not all(isinstance(arg, str) for arg in arguments): + raise ValueError('cmake_args must be an array of strings.') + # Only cache definitions are accepted: no alternate source/build/preset/toolchain/script. + if any(not arg.startswith('-D') or '=' not in arg or any(key in arg for key in + ('PA_LAB_PROFILE', 'CMAKE_HOME_DIRECTORY', 'CMAKE_TOOLCHAIN_FILE', 'CMAKE_PROJECT_', + 'CMAKE_USER_MAKE_RULES_OVERRIDE', 'CMAKE_CXX_COMPILER_LAUNCHER')) for arg in arguments): + raise ValueError('cmake_args accepts cache -DKEY=VALUE entries; protected build settings cannot be overridden.') + for key in ('worktree', 'build_dir', 'stage_root'): + candidate = Path(raw[key]).expanduser() + if not candidate.is_absolute(): + raise ValueError('All configured paths must be absolute (or start with ~/).') + candidate = candidate.resolve() + if candidate == Path.home() or candidate == Path('/'): + raise ValueError('Select dedicated worktree/build/staging directories.') + for previous in all_paths: + if candidate == previous or candidate in previous.parents or previous in candidate.parents: + raise ValueError('Worktree, build and staging paths must be separate across all slots.') + all_paths.append(candidate) + raw[key] = str(candidate) + if console not in slots: + raise ValueError('No configuration for console ' + console) + return dict(slots[console], console=console, profile='lab-' + console) + + +@contextmanager +def console_lock(console, root): + """Publish the existing lablock.sh protocol; never evict an existing owner.""" + lock = Path(root) / 'locks' / console + lock.parent.mkdir(parents=True, exist_ok=True) + try: + lock.mkdir() + except FileExistsError: + raise ValueError(f'Console {console} is locked. Use lab/control/lablock.sh -c {console} status; do not delete a live lock.') from None + token = secrets.token_hex(24) + try: + (lock / 'pid').write_text(str(os.getpid())) + (lock / 'token').write_text(token) + (lock / 'name').write_text('human-dev-' + console) + (lock / 'since').write_text(datetime.now().isoformat(timespec='seconds')) + yield token + finally: + if (lock / 'token').is_file() and (lock / 'token').read_text() == token: + shutil.rmtree(lock) + + +@contextmanager +def build_lock(root): + """Only one launcher may configure/build/stage locally at a time.""" + path = Path(root) / 'locks' / 'dev-build.lock' + path.parent.mkdir(parents=True, exist_ok=True) + with path.open('a') as stream: + try: + fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError: + raise ValueError('Another dev launcher is building; retry when that build finishes.') from None + yield + + +def run(command, *, cwd=None, env=None, capture=False): + """Supervise a process group, retaining locks through interruption and teardown.""" + print('+ ' + shlex.join(map(str, command)), flush=True) + child = None + interrupted_at = None + previous = {} + + def stop_child(signum, frame): + nonlocal interrupted_at + if interrupted_at is None: + interrupted_at = time.monotonic() + if child is not None: + try: + os.killpg(child.pid, signal.SIGTERM) + except ProcessLookupError: + pass + + for signum in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP): + previous[signum] = signal.signal(signum, stop_child) + try: + child = subprocess.Popen(command, cwd=cwd, env=env, start_new_session=True, + stdout=subprocess.PIPE if capture else None, text=True) + if interrupted_at is not None: + stop_child(signal.SIGTERM, None) + while True: + try: + output, _ = child.communicate(timeout=0.25) + break + except subprocess.TimeoutExpired: + if interrupted_at is not None and time.monotonic() - interrupted_at >= 10: + try: + os.killpg(child.pid, signal.SIGKILL) + except ProcessLookupError: + pass + if interrupted_at is not None: + raise KeyboardInterrupt + if child.returncode: + raise subprocess.CalledProcessError(child.returncode, command) + return output.strip() if capture else None + finally: + # Unexpected errors must not leave an unsupervised GUI after releasing ownership. + if child is not None and child.poll() is None: + try: + os.killpg(child.pid, signal.SIGKILL) + except ProcessLookupError: + pass + child.communicate() + for signum, handler in previous.items(): + signal.signal(signum, handler) + + +def git(slot, *arguments, runner=run): + return runner(['git', '-C', slot['worktree'], *arguments], capture=True) + + +def prepare_source(slot, runner=run): + """Switch only the configured clean lab worktree; update by fast-forward only.""" + worktree = Path(slot['worktree']).resolve() + actual = git(slot, 'rev-parse', '--show-toplevel', runner=runner) + if Path(actual).resolve() != worktree: + raise ValueError('Configured worktree must be the root of its own checkout.') + if git(slot, 'status', '--porcelain', '--untracked-files=all', runner=runner): + raise ValueError('Worktree is dirty; commit or preserve changes before starting.') + runner(['git', '-C', str(worktree), 'fetch', 'origin']) + runner(['git', '-C', str(worktree), 'switch', slot['branch']]) + remote = 'refs/remotes/origin/' + slot['branch'] + try: + git(slot, 'show-ref', '--verify', '--quiet', remote, runner=runner) + except subprocess.CalledProcessError as error: + if error.returncode != 1: + raise + print('No matching remote lab branch; preserving the configured local integration branch.', flush=True) + else: + runner(['git', '-C', str(worktree), 'merge', '--ff-only', 'origin/' + slot['branch']]) + # A marker or manifest field cannot prove native device enforcement is compiled. + git(slot, 'merge-base', '--is-ancestor', DEVICE_GUARD_REVISION, 'HEAD', runner=runner) + git(slot, 'merge-base', '--is-ancestor', 'origin/lab/main', 'HEAD', runner=runner) + tool = worktree / 'devtools/lab/lab_instance.py' + if not tool.is_file(): + raise ValueError('Selected branch lacks the instance-preparation tool (#236).') + return git(slot, 'rev-parse', 'HEAD', runner=runner) + + +def validate_profile(slot): + """Require deliberate setup; do not clone default settings or approve devices.""" + profile = Path.home() / 'Library/Application Support/SerialPrograms/Profiles' / slot['profile'] + policy = json.loads((profile / 'lab-devices.json').read_text()) + if not isinstance(policy, dict): + raise ValueError('lab-devices.json must be an object.') + if policy.get('profile') != slot['profile'] or policy.get('schema') != 1: + raise ValueError('Missing/mismatched lab-devices.json; follow DEVICE_OWNERSHIP.md first.') + return profile + + +def check_build_cache(slot): + """Do not repurpose another checkout's or another profile's cached build.""" + cache = Path(slot['build_dir']) / 'CMakeCache.txt' + if not cache.exists(): + return + values = {} + for line in cache.read_text().splitlines(): + if '=' in line and ':' in line.split('=', 1)[0]: + key, value = line.split('=', 1) + values[key.split(':', 1)[0]] = value + expected_source = Path(slot['worktree']) / 'SerialPrograms' + if Path(values.get('CMAKE_HOME_DIRECTORY', '/')).resolve() != expected_source: + raise ValueError('Build cache belongs to a different source checkout.') + if values.get('PA_LAB_PROFILE') != slot['profile']: + raise ValueError('Build cache is not bound to this lab profile; use a dedicated build directory.') + + +def copy_runtime_data(build, stage): + """macOS Main.cpp resolves runtime data beside the .app, outside its signature.""" + for name in ('Resources', 'Firmware', 'Scripts'): + source = Path(build) / name + if not source.is_dir(): + raise ValueError('Build is missing runtime directory ' + str(source)) + shutil.copytree(source, Path(stage) / name) + + +def start(slot, lock_root, runner=run): + """Build, sign, verify and run; all failures stop before the next stage.""" + env = os.environ.copy() + with console_lock(slot['console'], lock_root) as token: + env.update(LAB_CONSOLE=slot['console'], LAB_PROFILE_NAME=slot['profile'], + LABLOCK_TOKEN=token, LAB_DIR=str(lock_root)) + with build_lock(lock_root): + revision = prepare_source(slot, runner) + profile = validate_profile(slot) + env['LAB_PROFILE'] = str(profile) + check_build_cache(slot) + source = Path(slot['worktree']) / 'SerialPrograms' + build = Path(slot['build_dir']) + runner(['cmake', '-S', str(source), '-B', str(build), + *slot.get('cmake_args', []), '-DPA_LAB_PROFILE=' + slot['profile']], env=env) + runner(['cmake', '--build', str(build), '--parallel', '4'], env=env) + if git(slot, 'status', '--porcelain', '--untracked-files=all', runner=runner): + raise ValueError('Source changed during build; refusing deployment.') + if git(slot, 'rev-parse', 'HEAD', runner=runner) != revision: + raise ValueError('Source revision changed during build; refusing deployment.') + app = build / 'SerialPrograms.app' + receipt = json.loads((app / 'Contents/MacOS/SerialPrograms.lab-build.json').read_text()) + if receipt.get('source_revision') != revision: + raise ValueError('Linked receipt is stale for this source revision; relink through the normal build before retrying.') + tool = Path(slot['worktree']) / 'devtools/lab/lab_instance.py' + stage = Path(slot['stage_root']) / (revision[:12] + '-' + secrets.token_hex(4)) + stage.parent.mkdir(parents=True, exist_ok=True) + runner([sys.executable, str(tool), 'stage', '--app', str(app), '--out', str(stage), + '--profile', slot['profile'], '--console', slot['console'], + '--bundle-id', slot['bundle_id'], '--signing-identity', slot['signing_identity']], env=env) + copy_runtime_data(build, stage) + runner([sys.executable, str(tool), 'verify', '--manifest', str(stage / 'lab-deployment.json'), + '--profile', slot['profile']], env=env) + executable = stage / 'SerialPrograms.app/Contents/MacOS/SerialPrograms' + print(f'Running console {slot["console"]}, profile {slot["profile"]}, source {revision}. ' + 'Quit the GUI to release the console lock.', flush=True) + # Direct child, never `open`: the console lock outlives the actual GUI process. + runner([str(executable), '--profile', slot['profile']], cwd=str(stage), env=env) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument('console', choices=['A', 'B']) + parser.add_argument('--config', type=Path, default=DEFAULT_CONFIG) + parser.add_argument('--plan', action='store_true', help='Print resolved setup without locks, fetch/build or launch') + args = parser.parse_args() + try: + slot = load_config(args.config, args.console) + if args.plan: + print(json.dumps(slot, indent=2)) + return 0 + if sys.platform != 'darwin': + raise ValueError('GUI development launching is supported only on macOS.') + start(slot, Path(os.environ.get('LAB_DIR', str(Path.home() / '.lab')))) + except KeyboardInterrupt: + print('Development instance stopped; its child exited before locks were released.', file=sys.stderr) + return 130 + except (OSError, ValueError, KeyError, TypeError, subprocess.CalledProcessError) as error: + print('Dev instance refused: ' + str(error), file=sys.stderr) + return 2 + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/lab/scripts/test_start_dev.py b/lab/scripts/test_start_dev.py new file mode 100644 index 0000000000..6fc4f30f1c --- /dev/null +++ b/lab/scripts/test_start_dev.py @@ -0,0 +1,301 @@ +"""Offline launcher tests: python3 -m unittest discover -s lab/scripts -p test_start_dev.py -v.""" + +from contextlib import redirect_stdout +import io +import json +import os +from pathlib import Path +import signal +import subprocess +import sys +import tempfile +import time +import unittest +from unittest.mock import patch + +import start_dev as dev + + +class ConfigurationTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.slot = dict(worktree=str(self.root / 'src-A'), branch='lab/dev-A', + build_dir=str(self.root / 'build-A'), stage_root=str(self.root / 'stage-A'), + bundle_id='com.dayfine.pokemonautomation.labA', signing_identity='Local Development') + self.data = {'schema': 1, 'slots': {'A': self.slot}} + self.path = self.root / 'config.json' + + def load(self): + self.path.write_text(json.dumps(self.data)) + return dev.load_config(self.path, 'A') + + def test_profile_and_console_are_bound_by_slot(self): + slot = self.load() + self.assertEqual(('A', 'lab-A'), (slot['console'], slot['profile'])) + + def test_refuses_feature_branch_default_identity_and_ad_hoc_signing(self): + for key, value in [('branch', 'swsh/feature'), ('branch', 'lab/../main'), + ('bundle_id', 'PokemonAutomation.SerialPrograms'), ('signing_identity', '-')]: + with self.subTest(key=key, value=value): + self.data['slots']['A'] = dict(self.slot, **{key: value}) + with self.assertRaises(ValueError): + self.load() + + def test_refuses_nested_shared_or_relative_directories(self): + for value in [self.slot['worktree'], str(Path(self.slot['worktree']) / 'build'), 'relative']: + with self.subTest(value=value): + self.data['slots']['A'] = dict(self.slot, build_dir=value) + with self.assertRaises(ValueError): + self.load() + + def test_two_slots_must_have_distinct_paths_and_identities(self): + second = dict(self.slot, worktree=str(self.root / 'src-B'), build_dir=str(self.root / 'build-B'), + stage_root=str(self.root / 'stage-B'), bundle_id='com.dayfine.pokemonautomation.labB') + self.data['slots']['B'] = second + self.load() + for key in ['worktree', 'build_dir', 'stage_root', 'bundle_id']: + with self.subTest(key=key): + self.data['slots']['B'] = dict(second, **{key: self.slot[key]}) + with self.assertRaises(ValueError): + self.load() + + def test_build_settings_cannot_override_profile_or_command_mode(self): + for args in [['-DPA_LAB_PROFILE=default'], ['-P', '/tmp/script.cmake'], + ['--preset=release'], ['-DCMAKE_PROJECT_INCLUDE=/tmp/override.cmake']]: + with self.subTest(args=args): + self.data['slots']['A'] = dict(self.slot, cmake_args=args) + with self.assertRaises(ValueError): + self.load() + self.data['slots']['A'] = dict(self.slot, cmake_args=['-DCMAKE_BUILD_TYPE=RelWithDebInfo']) + self.load() + + +class OwnershipTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + + def test_same_console_refused_different_console_allowed(self): + with dev.console_lock('A', self.root) as token: + with self.assertRaises(ValueError): + with dev.console_lock('A', self.root): + self.fail('second owner admitted') + with dev.console_lock('B', self.root): + self.assertEqual(token, (self.root / 'locks/A/token').read_text()) + self.assertFalse((self.root / 'locks/A').exists()) + + def test_exception_releases_own_lock(self): + with self.assertRaises(RuntimeError): + with dev.console_lock('A', self.root): + raise RuntimeError('build failed') + self.assertFalse((self.root / 'locks/A').exists()) + + def test_existing_shell_helpers_see_the_same_ownership(self): + helper = Path(__file__).resolve().parents[1] / 'control/lablock.sh' + with dev.console_lock('A', self.root) as token: + env = dict(os.environ, LAB_DIR=str(self.root)) + env.pop('LABLOCK_TOKEN', None) + refused = subprocess.run(['sh', str(helper), '-c', 'A', 'check'], env=env, capture_output=True) + self.assertEqual(3, refused.returncode) + allowed = subprocess.run(['sh', str(helper), '-c', 'A', 'check'], + env=dict(env, LABLOCK_TOKEN=token), capture_output=True) + self.assertEqual(0, allowed.returncode) + + def test_build_is_exclusive_even_between_different_consoles(self): + with dev.build_lock(self.root): + with self.assertRaises(ValueError): + with dev.build_lock(self.root): + self.fail('parallel build admitted') + with dev.build_lock(self.root): + pass + + def test_interrupt_keeps_console_lock_through_child_teardown(self): + # The "app" is a temporary Python process; no GUI, settings or hardware. + child = self.root / 'child.py' + ready, exited = self.root / 'ready', self.root / 'exited' + child.write_text('''import signal, time +from pathlib import Path +import sys +def stop(*args): + assert Path(sys.argv[1]).is_dir(), 'ownership released before child exit' + time.sleep(0.2) + assert Path(sys.argv[1]).is_dir(), 'ownership released during teardown' + Path(sys.argv[3]).write_text('clean exit') + sys.exit(0) +signal.signal(signal.SIGTERM, stop) +Path(sys.argv[2]).touch() +while True: time.sleep(0.05) +''') + supervisor = self.root / 'supervisor.py' + supervisor.write_text('''import sys +from pathlib import Path +sys.path.insert(0, sys.argv[1]) +import start_dev as dev +try: + with dev.console_lock('A', sys.argv[2]): + dev.run([sys.executable, sys.argv[3], sys.argv[4], sys.argv[5], sys.argv[6]]) +except KeyboardInterrupt: + sys.exit(130) +''') + proc = subprocess.Popen([sys.executable, str(supervisor), str(Path(dev.__file__).parent), + str(self.root), str(child), str(self.root / 'locks/A'), str(ready), str(exited)], + stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) + try: + deadline = time.monotonic() + 5 + while not ready.exists() and proc.poll() is None and time.monotonic() < deadline: + time.sleep(0.01) + self.assertTrue(ready.exists(), 'temporary child did not start') + proc.send_signal(signal.SIGTERM) + output, error = proc.communicate(timeout=5) + self.assertEqual(130, proc.returncode, output + error) + self.assertEqual('clean exit', exited.read_text()) + self.assertFalse((self.root / 'locks/A').exists()) + finally: + if proc.poll() is None: + proc.kill() + proc.communicate() + + +class PipelineTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.slot = dict(console='A', profile='lab-A', worktree=str(self.root / 'src'), branch='lab/dev-A', + build_dir=str(self.root / 'build'), stage_root=str(self.root / 'stage'), + bundle_id='com.dayfine.pokemonautomation.labA', signing_identity='Local Development') + self.revision = 'a' * 40 + receipt = Path(self.slot['build_dir']) / 'SerialPrograms.app/Contents/MacOS/SerialPrograms.lab-build.json' + receipt.parent.mkdir(parents=True) + receipt.write_text(json.dumps({'source_revision': self.revision})) + self.calls = [] + + def runner(self, command, **kwargs): + self.calls.append((command, kwargs)) + if command[0] == 'git': + return self.revision if command[-2:] == ['rev-parse', 'HEAD'] else '' + if command[0].endswith('/SerialPrograms'): + lock = self.root / 'locks/A' + self.assertTrue(lock.is_dir(), 'lock must outlive actual GUI') + self.assertEqual((lock / 'token').read_text(), kwargs['env']['LABLOCK_TOKEN']) + # Build lock has already been released: the other console may now build. + with dev.build_lock(self.root): + pass + + def execute(self, runner=None): + with patch.object(dev, 'prepare_source', return_value=self.revision), \ + patch.object(dev, 'validate_profile', return_value=self.root / 'profile'), \ + patch.object(dev, 'copy_runtime_data'), \ + redirect_stdout(io.StringIO()): + dev.start(self.slot, self.root, runner or self.runner) + + def test_sequence_binds_build_then_signs_verifies_and_runs_direct_child(self): + self.execute() + commands = [command for command, _ in self.calls] + self.assertIn('-DPA_LAB_PROFILE=lab-A', commands[0]) + self.assertEqual(['cmake', '--build', self.slot['build_dir'], '--parallel', '4'], commands[1]) + self.assertEqual('stage', commands[4][2]) + self.assertEqual('verify', commands[5][2]) + self.assertEqual(['--profile', 'lab-A'], commands[-1][-2:]) + self.assertFalse((self.root / 'locks/A').exists()) + + def test_each_build_stage_or_verify_failure_prevents_launch(self): + for failure in ['build', 'stage', 'verify']: + with self.subTest(failure=failure): + self.calls.clear() + def failing(command, **kwargs): + if ('--build' in command if failure == 'build' else failure in command): + raise subprocess.CalledProcessError(1, command) + return self.runner(command, **kwargs) + with self.assertRaises(subprocess.CalledProcessError): + self.execute(failing) + self.assertFalse(any(cmd[0].endswith('/SerialPrograms') for cmd, _ in self.calls)) + self.assertFalse((self.root / 'locks/A').exists()) + + def test_changed_revision_after_build_prevents_staging(self): + def changed(command, **kwargs): + result = self.runner(command, **kwargs) + return 'b' * 40 if command[-2:] == ['rev-parse', 'HEAD'] else result + with self.assertRaisesRegex(ValueError, 'revision changed'): + self.execute(changed) + self.assertFalse(any('stage' in cmd for cmd, _ in self.calls)) + + def test_runtime_directories_are_copied_beside_app_and_missing_data_is_refused(self): + build, stage = self.root / 'data-build', self.root / 'data-stage' + for name in ['Resources', 'Firmware', 'Scripts']: + (build / name).mkdir(parents=True) + (build / name / 'fixture.txt').write_text(name) + stage.mkdir() + dev.copy_runtime_data(build, stage) + for name in ['Resources', 'Firmware', 'Scripts']: + self.assertEqual(name, (stage / name / 'fixture.txt').read_text()) + with self.assertRaisesRegex(ValueError, 'missing runtime directory'): + dev.copy_runtime_data(self.root / 'missing', self.root / 'unused') + + def test_cache_cannot_cross_source_or_profile(self): + cache = Path(self.slot['build_dir']) / 'CMakeCache.txt' + for source, profile in [('/other/source', 'lab-A'), (self.slot['worktree'] + '/SerialPrograms', 'lab-B')]: + with self.subTest(source=source, profile=profile): + cache.write_text(f'CMAKE_HOME_DIRECTORY:INTERNAL={source}\nPA_LAB_PROFILE:STRING={profile}\n') + with self.assertRaises(ValueError): + dev.check_build_cache(self.slot) + + +class SourceTests(unittest.TestCase): + def test_dirty_worktree_stops_before_fetch_or_switch(self): + calls = [] + slot = {'worktree': '/temporary/source', 'branch': 'lab/dev-A'} + def runner(command, **kwargs): + calls.append(command) + return slot['worktree'] if command[-1] == '--show-toplevel' else ' M changed.cpp' + with self.assertRaisesRegex(ValueError, 'dirty'): + dev.prepare_source(slot, runner) + self.assertEqual(2, len(calls)) + + +class GitIntegrationTests(unittest.TestCase): + def test_real_checkout_switch_and_fast_forward_preserve_other_branch(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + remote, checkout = root / 'origin', root / 'worktree' + def git(path, *args): + return subprocess.run(['git', '-C', str(path), *args], check=True, + text=True, capture_output=True).stdout.strip() + subprocess.run(['git', 'init', '-b', 'lab/main', str(remote)], check=True, capture_output=True) + git(remote, 'config', 'user.email', 'fixture@example.invalid') + git(remote, 'config', 'user.name', 'Launcher test') + tool = remote / 'devtools/lab/lab_instance.py' + tool.parent.mkdir(parents=True) + tool.write_text('# temporary offline fixture\n') + git(remote, 'add', '.') + git(remote, 'commit', '-m', 'Fixture guard base') + guard = git(remote, 'rev-parse', 'HEAD') + git(remote, 'switch', '-c', 'lab/dev-A') + subprocess.run(['git', 'clone', '--branch', 'lab/main', str(remote), str(checkout)], + check=True, capture_output=True) + slot = {'worktree': str(checkout), 'branch': 'lab/dev-A'} + with patch.object(dev, 'DEVICE_GUARD_REVISION', guard), redirect_stdout(io.StringIO()): + self.assertEqual(guard, dev.prepare_source(slot)) + self.assertEqual('lab/dev-A', git(checkout, 'branch', '--show-current')) + (remote / 'new.txt').write_text('new remote commit') + git(remote, 'add', '.') + git(remote, 'commit', '-m', 'Advance selected lab branch') + newest = git(remote, 'rev-parse', 'HEAD') + self.assertEqual(newest, dev.prepare_source(slot)) + self.assertEqual(guard, git(checkout, 'rev-parse', 'lab/main')) + git(checkout, 'switch', '-c', 'lab/local-only') + local_slot = dict(slot, branch='lab/local-only') + self.assertEqual(newest, dev.prepare_source(local_slot)) + git(checkout, 'switch', slot['branch']) + # A local untracked file must survive, and stop all switching/updating. + (checkout / 'user.txt').write_text('keep this') + with self.assertRaisesRegex(ValueError, 'dirty'): + dev.prepare_source(slot) + self.assertEqual('keep this', (checkout / 'user.txt').read_text()) + + +if __name__ == '__main__': + unittest.main()