From d96e448b922d1b1417486d3d646dec6f264ccc99 Mon Sep 17 00:00:00 2001 From: Eli Fine Date: Tue, 31 Mar 2026 20:47:38 +0000 Subject: [PATCH 1/4] copier --- .claude/commands/red.md | 15 ++++++++++++ .claude/settings/permissions/bash.jsonc | 21 ++++++++++++++++- .coderabbit.yaml | 2 ++ .copier-answers.yml | 2 +- .devcontainer/devcontainer.json | 2 +- .devcontainer/manual-setup-deps.py | 23 +++++++++++++++++++ .github/actions/install_deps/action.yml | 7 +++++- .github/workflows/ci.yaml | 2 ++ .github/workflows/pre-commit.yaml | 1 + AGENTS.md | 17 ++++++++++---- extensions/context.py | 6 ++--- template/.claude/commands/red.md | 15 ++++++++++++ .../.claude/settings/permissions/bash.jsonc | 21 ++++++++++++++++- template/.coderabbit.yaml | 2 ++ template/.devcontainer/manual-setup-deps.py | 23 +++++++++++++++++++ .../.github/actions/install_deps/action.yml | 7 +++++- template/.github/workflows/ci.yaml.jinja | 9 ++++++-- template/.github/workflows/pre-commit.yaml | 1 + template/AGENTS.md | 17 ++++++++++---- 19 files changed, 174 insertions(+), 19 deletions(-) diff --git a/.claude/commands/red.md b/.claude/commands/red.md index e61208773..01dc7124d 100644 --- a/.claude/commands/red.md +++ b/.claude/commands/red.md @@ -94,6 +94,21 @@ This phase is **not part of the regular TDD workflow** and must only be applied - Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**. - A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior. +### If a New Test Passes Immediately + +If a newly written test passes without any implementation change, do not assume it is correct. Verify it actually exercises the intended behavior: + +1. Identify the implementation line most likely responsible for the pass +2. Temporarily remove that line +3. Run the **full test suite** (not just the new test) + +Then interpret the result: + +- **Only the new test fails** — the line was never driven by a prior test. This is accidental over-implementation: delete the line permanently and proceed to the green phase to reintroduce it properly. +- **Other existing tests also fail** — the line was already legitimately required by prior work. The new test is valid regression coverage. Restore the line; the test is confirmed correct as written. + +In both cases, confirm the new test fails for the expected reason before proceeding (the right assertion, not a syntax or import error). + ### General Information - Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck. diff --git a/.claude/settings/permissions/bash.jsonc b/.claude/settings/permissions/bash.jsonc index 92caa8a23..bdf277175 100644 --- a/.claude/settings/permissions/bash.jsonc +++ b/.claude/settings/permissions/bash.jsonc @@ -74,9 +74,17 @@ "Bash(tail *)", // Search "Bash(rg *)", + // Research + "Bash(gh issue list *)", + "Bash(gh pr view *)", + "Bash(gh pr diff *)" ], "ask": [ - "Bash(gh *)", // let's hold off before we let it use the github CLI in any free running allow mode...I don't want it somehow approving PRs with the user's credentials + // let's hold off before we let it use the github CLI in any free running allow mode...I don't want it somehow approving PRs with the user's credentials + "Bash(gh repo *)", + "Bash(gh release *)", + "Bash(gh secret *)", + "Bash(gh ruleset *)", "Bash(aws *)", // let's hold off before we let it use AWS CLI in any free running allow mode. We need to be very sure we don't have any access to staging or production credentials in our dev environment (...which we shouldn't...but we need to double check that or consider any other safeguards first) "Bash(curl *)", "Bash(ln *)", @@ -85,6 +93,17 @@ "deny": [ // Exceptions to generally allowed AI tooling "Bash(bd init*)", // we need to control the init process, don't let AI do that in the background + // Github + // Claude should not ever interfere with the PR process, that is how we gate AI's work + "Bash(gh pr create *)", + "Bash(gh pr edit *)", + "Bash(gh pr ready *)", + "Bash(gh pr review *)", + "Bash(gh pr merge *)", + "Bash(gh pr close *)", + "Bash(gh pr comment *)", + "Bash(gh pr update-branch *)", + // Destructive File Operations "Bash(chmod -R *)", "Bash(chown -R *)", diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 1d2e81ac2..372316baf 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -7,6 +7,8 @@ reviews: instructions: "These files came from a vendor and we're not allowed to change them. Refer to it if you need to understand how the main code interacts with it, but do not make comments about it." - path: "**/*.py" instructions: "Check the `ruff.toml` and `ruff-test.toml` for linting rules we've explicitly disabled and don't suggest changes to please conventions we've disabled. Do not express concerns about ruff rules; a pre-commit hook already runs a ruff check. Do not warn about unnecessary super().__init__() calls; pyright prefers those to be present. Do not warn about missing type hints; a pre-commit hook already checks for that." + - path: "**/.copier-answers.yml" + instructions: "Do not comment about the `_commit` value needing to be a clean release tag. A CI job will fail if that is not the case." tools: eslint: # when the code contains typescript, eslint will be run by pre-commit, and coderabbit often generates false positives enabled: false diff --git a/.copier-answers.yml b/.copier-answers.yml index 1ab5c68eb..13ed228d8 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: v0.0.107 +_commit: v0.0.110 _src_path: gh:LabAutomationAndScreening/copier-base-template.git description: A web app that is hosted within a local intranet. Nuxt frontend, python backend, docker-compose diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index cce216e01..855d505f3 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -65,5 +65,5 @@ "initializeCommand": "sh .devcontainer/initialize-command.sh", "onCreateCommand": "sh .devcontainer/on-create-command.sh", "postStartCommand": "sh .devcontainer/post-start-command.sh" - // Devcontainer context hash (do not manually edit this, it's managed by a pre-commit hook): 80d9f36a # spellchecker:disable-line + // Devcontainer context hash (do not manually edit this, it's managed by a pre-commit hook): 69f80248 # spellchecker:disable-line } diff --git a/.devcontainer/manual-setup-deps.py b/.devcontainer/manual-setup-deps.py index 6f6fe0d8e..19a1c15ef 100644 --- a/.devcontainer/manual-setup-deps.py +++ b/.devcontainer/manual-setup-deps.py @@ -11,6 +11,7 @@ REPO_ROOT_DIR = Path(__file__).parent.parent.resolve() ENVS_CONFIG = REPO_ROOT_DIR / ".devcontainer" / "envs.json" +PULUMI_CLI_INSTALL_SCRIPT = REPO_ROOT_DIR / ".devcontainer" / "install-pulumi-cli.sh" UV_PYTHON_ALREADY_CONFIGURED = "UV_PYTHON" in os.environ parser = argparse.ArgumentParser(description="Manual setup for dependencies in the repo") _ = parser.add_argument( @@ -44,6 +45,12 @@ default=False, help="Allow uv to install new versions of Python on the fly. This is typically only needed when instantiating the copier template.", ) +_ = parser.add_argument( + "--skip-installing-pulumi-cli", + action="store_true", + default=False, + help="Do not install the Pulumi CLI even if the lock file references it", +) class PackageManager(str, enum.Enum): @@ -127,6 +134,22 @@ def main(): check=True, env=uv_env, ) + if ( + not generate_lock_file_only + and not args.skip_installing_pulumi_cli + and platform.system() == "Linux" + and env.lock_file.exists() + and '"pulumi"' in env.lock_file.read_text() + ): + if not PULUMI_CLI_INSTALL_SCRIPT.exists(): + print( + f"Pulumi CLI install script not found at {PULUMI_CLI_INSTALL_SCRIPT}, skipping Pulumi CLI installation" + ) + else: + _ = subprocess.run( + ["sh", str(PULUMI_CLI_INSTALL_SCRIPT), str(env.lock_file)], + check=True, + ) elif env.package_manager == PackageManager.PNPM: pnpm_command = ["pnpm", "install", "--dir", str(env.path)] if env_check_lock: diff --git a/.github/actions/install_deps/action.yml b/.github/actions/install_deps/action.yml index 0cedd63a3..7e22d8410 100644 --- a/.github/actions/install_deps/action.yml +++ b/.github/actions/install_deps/action.yml @@ -44,6 +44,11 @@ inputs: description: Whether to skip updating the hash when running manual-setup-deps.py default: true required: false + skip-installing-pulumi-cli: + type: boolean + description: Whether to skip installing the Pulumi CLI even if the lock file references it + default: false + required: false runs: @@ -83,5 +88,5 @@ runs: - name: Install dependencies # the funky syntax is github action ternary if: ${{ inputs.install-deps }} - run: python .devcontainer/manual-setup-deps.py ${{ inputs.python-version == 'notUsing' && '--no-python' || '' }} ${{ inputs.node-version == 'notUsing' && '--no-node' || '' }} ${{ inputs.skip-updating-devcontainer-hash && '--skip-updating-devcontainer-hash' || '' }} + run: python .devcontainer/manual-setup-deps.py ${{ inputs.python-version == 'notUsing' && '--no-python' || '' }} ${{ inputs.node-version == 'notUsing' && '--no-node' || '' }} ${{ inputs.skip-updating-devcontainer-hash && '--skip-updating-devcontainer-hash' || '' }} ${{ inputs.skip-installing-pulumi-cli && '--skip-installing-pulumi-cli' || '' }} shell: pwsh diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 33efdd3ed..f6d7f4fca 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -13,6 +13,7 @@ env: permissions: id-token: write # needed to assume OIDC roles (e.g. for downloading from CodeArtifact) + contents: read # need to explicitly provide this whenever defining permissions because the default value is 'none' for anything not explicitly set when permissions are defined jobs: get-values: @@ -22,6 +23,7 @@ jobs: check-skip-duplicate: runs-on: ubuntu-24.04 + timeout-minutes: 2 outputs: should-run: ${{ steps.check.outputs.should-run }} steps: diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index ffeb94851..fbdeb8605 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.github/workflows/pre-commit.yaml @@ -50,6 +50,7 @@ jobs: python-version: ${{ inputs.python-version }} node-version: ${{ inputs.node-version }} skip-installing-ssm-plugin-manager: true + skip-installing-pulumi-cli: true - name: Set up mutex # Github concurrency management is horrible, things get arbitrarily cancelled if queued up. So using mutex until github fixes itself. When multiple jobs are modifying cache at once, weird things can happen. possible issue is https://github.com/actions/toolkit/issues/658 if: ${{ runner.os != 'Windows' }} # we're just gonna have to YOLO on Windows, because this action doesn't support it yet https://github.com/ben-z/gh-action-mutex/issues/14 diff --git a/AGENTS.md b/AGENTS.md index a6e5c8360..221d97352 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,24 +17,32 @@ This project is a Copier template used to generate applications that are able to ## Testing -- Always run tests with an explicit path (e.g. uv run pytest tests/unit) — test runners discover all types by default. +- Always run tests with an explicit path (e.g. uv run pytest tests/unit) — test runners discover all types (unit, integration, E2E...) by default. +- When iterating on a single test, run that test in isolation first and confirm it is in the expected state (red or green) before widening to the full suite. Use the most targeted invocation available: a specific test function for Python (e.g. `uv run pytest path/to/test.py::test_name --no-cov`) or a file path and name filter for TypeScript (e.g. `pnpm test-unit -- path/to/test.spec.ts -t "test name" --no-coverage`). Only run the full suite once the target test behaves as expected. - Test coverage requirements are usually at 100%, so when running a subset of tests, always disable test coverage to avoid the test run failing for insufficient coverage. - Avoid magic values in comparisons in tests in all languages (like ruff rule PLR2004 specifies) - Prefer using random values in tests rather than arbitrary ones (e.g. the faker library, uuids, random.randint) when possible. For enums, pick randomly rather than hardcoding one value. - Avoid loops in tests — assert each item explicitly so failures pinpoint the exact element. When verifying a condition across all items in a collection, collect the violations into a list and assert it's empty (e.g., assert [x for x in items if bad_condition(x)] == []). -- Key `data-testid` selectors off unique IDs (e.g. UUIDs), not human-readable names which may collide or change. +- When a test's final assertion is an absence (e.g., element is `null`, list is empty, modal is closed), include a prior presence assertion confirming the expected state existed before the action that removed it. A test whose only assertion is an absence check can pass vacuously if setup silently failed. +- When asserting a mock or spy was called with specific arguments, always constrain as tightly as possible. In order of preference: (1) assert called exactly once with those args (`assert_called_once_with` in Python, `toHaveBeenCalledExactlyOnceWith` in Vitest/Jest); (2) if multiple calls are expected, assert the total call count and use a positional or last-call assertion (`nthCalledWith`, `lastCalledWith` / `assert_has_calls` with `call_args_list[n]`); (3) plain "called with at any point" (`toHaveBeenCalledWith`, `assert_called_with`) is a last resort only when neither the call count nor the call order can reasonably be constrained. ### Python Testing -- When using `mocker.spy` on a class-level method (including inherited ones), the spy records the unbound call, so assertions need `ANY` as the first argument to match self: `spy.assert_called_once_with(ANY, expected_arg)` +- When using `mocker.spy` on a class-level method (including inherited ones), the spy records the unbound call, so assertions need `ANY` as the first argument to match self: `spy.assert_called_once_with(ANY, expected_arg)` - Before writing new mock/spy helpers, check the `tests/unit/` folder for pre-built helpers in files like `fixtures.py` or `*mocks.py` - When a test needs a fixture only for its side effects (not its return value), use `@pytest.mark.usefixtures(fixture_name.__name__)` instead of adding an unused parameter with a noqa comment - Use `__name__` instead of string literals when referencing functions/methods (e.g., `mocker.patch.object(MyClass, MyClass.method.__name__)`, `pytest.mark.usefixtures(my_fixture.__name__)`). This enables IDE refactoring tools to catch renames. - When using the faker library, prefer the pytest fixture (provided by the faker library) over instantiating instances of Faker. +- **Choosing between cassettes and mocks:** At the layer that directly wraps an external API or service, strongly prefer VCR cassette-recorded interactions (via pytest-recording/vcrpy) — they capture real HTTP traffic and verify the wire format, catching integration issues that mocks would miss. At layers above that (e.g. business logic, route handlers), mock the wrapper layer instead (e.g. `mocker.patch.object(ThresholdsRepository, ...)`) — there is no value in re-testing the HTTP interaction from higher up. - **Never hand-write VCR cassette YAML files.** Cassettes must be recorded from real HTTP interactions by running the test once with `--record-mode=once` against a live external service: `uv run pytest --record-mode=once --no-cov`. The default mode is `none` — a missing cassette will cause an error, which is expected until recorded. - **Never hand-edit syrupy snapshot files.** Snapshots are auto-generated — to create or update them, run `uv run pytest --snapshot-update --no-cov`. A missing snapshot causes the test to fail, which is expected until you run with `--snapshot-update`. When a snapshot mismatch occurs, fix the code if the change was unintentional; run `--snapshot-update` if it was intentional. - **Never hand-write or hand-edit pytest-reserial `.jsonl` recording files.** Recordings must be captured from real serial port traffic by running the test with `--record` while the device is connected: `uv run pytest --record --no-cov`. The default mode replays recordings — a missing recording causes an error, which is expected until recorded against a live device. +### Frontend Testing + +- Key `data-testid` selectors off unique IDs (e.g. UUIDs), not human-readable names which may collide or change. +- In DOM-based tests, scope queries to the tightest relevant container. Only query `document` or `document.body` directly to find the top-level portal/popup element (e.g. a Reka UI dialog via `[role="dialog"][data-state="open"]`); all further queries should run on that element, not on `document.body` again. + # Agent Implementations & Configurations ## Memory and Rules @@ -49,7 +57,8 @@ This project is a Copier template used to generate applications that are able to - For frontend tests, run commands via `pnpm` scripts from `frontend/package.json` — never invoke tools directly (not pnpm exec , npx , etc.). ✅ pnpm test-unit ❌ pnpm vitest ... or npx vitest ... - For linting and type-checking, prefer `pre-commit run ` over invoking tools directly — this matches the permission allow-list and mirrors what CI runs. Key hook IDs: `typescript-check`, `eslint`, `pyright`, `ruff`, `ruff-format`. - Never rely on IDE diagnostics for ruff warnings — the IDE may not respect the project's ruff.toml config. Run `pre-commit run ruff -a` to get accurate results. -- When running terminal commands, execute exactly one command per tool call. Do not chain commands with &&, ||, ;, or & — this prohibition has no exceptions, even for `cd && ...` patterns. Use absolute paths instead of `cd` to avoid needing to chain. Pipes (|) are allowed for output transformation (e.g., head, tail, grep). If two sequential commands are needed, run them in separate tool calls. Chained commands break the permission allow-list matcher and cause unnecessary permission prompts +- When running terminal commands, execute exactly one command per tool call. Do not chain commands with &&, ||, ;, or & — this prohibition has no exceptions, even for `cd && ...` patterns. Use `cd` to change to the directory you want before running the command, avoiding the need to chain. Pipes (|) are allowed for output transformation (e.g., head, tail, grep). If two sequential commands are needed, run them in separate tool calls. Chained commands break the permission allow-list matcher and cause unnecessary permission prompts +- Never use `pnpm --prefix ` or `uv --directory ` to target a different directory — these flags break the permission allow-list matcher the same way chained `cd &&` commands do. Instead, rely on the working directory already being correct (the cwd persists between Bash tool calls), or issue a plain `cd ` as a separate prior tool call to reposition before running the command. - Never use backslash line continuations in shell commands — always write the full command on a single line. Backslashes break the permission allow-list matcher. - **Never manually edit files in any `generated/` folder.** These files are produced by codegen tooling (typically Kiota) and any manual changes will be overwritten. If a generated file needs to change, update the source (e.g. the OpenAPI schema) and re-run the generator. diff --git a/extensions/context.py b/extensions/context.py index 02f60eccf..e6dde77b1 100644 --- a/extensions/context.py +++ b/extensions/context.py @@ -21,12 +21,12 @@ def hook(self, context: dict[Any, Any]) -> dict[Any, Any]: context["copier_version"] = "==9.14.0" context["copier_template_extensions_version"] = "==0.3.3" context["sphinx_version"] = "9.0.4" - context["pulumi_version"] = ">=3.226.0" + context["pulumi_version"] = ">=3.228.0" context["pulumi_aws_version"] = ">=7.23.0" - context["pulumi_aws_native_version"] = ">=1.57.0" + context["pulumi_aws_native_version"] = ">=1.59.0" context["pulumi_command_version"] = ">=1.2.1" context["pulumi_github_version"] = ">=6.12.1" - context["pulumi_okta_version"] = ">=6.2.3" + context["pulumi_okta_version"] = ">=6.4.0" context["boto3_version"] = ">=1.42.53" context["ephemeral_pulumi_deploy_version"] = ">=0.0.6" context["pydantic_version"] = ">=2.12.5" diff --git a/template/.claude/commands/red.md b/template/.claude/commands/red.md index e61208773..01dc7124d 100644 --- a/template/.claude/commands/red.md +++ b/template/.claude/commands/red.md @@ -94,6 +94,21 @@ This phase is **not part of the regular TDD workflow** and must only be applied - Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**. - A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior. +### If a New Test Passes Immediately + +If a newly written test passes without any implementation change, do not assume it is correct. Verify it actually exercises the intended behavior: + +1. Identify the implementation line most likely responsible for the pass +2. Temporarily remove that line +3. Run the **full test suite** (not just the new test) + +Then interpret the result: + +- **Only the new test fails** — the line was never driven by a prior test. This is accidental over-implementation: delete the line permanently and proceed to the green phase to reintroduce it properly. +- **Other existing tests also fail** — the line was already legitimately required by prior work. The new test is valid regression coverage. Restore the line; the test is confirmed correct as written. + +In both cases, confirm the new test fails for the expected reason before proceeding (the right assertion, not a syntax or import error). + ### General Information - Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck. diff --git a/template/.claude/settings/permissions/bash.jsonc b/template/.claude/settings/permissions/bash.jsonc index 92caa8a23..bdf277175 100644 --- a/template/.claude/settings/permissions/bash.jsonc +++ b/template/.claude/settings/permissions/bash.jsonc @@ -74,9 +74,17 @@ "Bash(tail *)", // Search "Bash(rg *)", + // Research + "Bash(gh issue list *)", + "Bash(gh pr view *)", + "Bash(gh pr diff *)" ], "ask": [ - "Bash(gh *)", // let's hold off before we let it use the github CLI in any free running allow mode...I don't want it somehow approving PRs with the user's credentials + // let's hold off before we let it use the github CLI in any free running allow mode...I don't want it somehow approving PRs with the user's credentials + "Bash(gh repo *)", + "Bash(gh release *)", + "Bash(gh secret *)", + "Bash(gh ruleset *)", "Bash(aws *)", // let's hold off before we let it use AWS CLI in any free running allow mode. We need to be very sure we don't have any access to staging or production credentials in our dev environment (...which we shouldn't...but we need to double check that or consider any other safeguards first) "Bash(curl *)", "Bash(ln *)", @@ -85,6 +93,17 @@ "deny": [ // Exceptions to generally allowed AI tooling "Bash(bd init*)", // we need to control the init process, don't let AI do that in the background + // Github + // Claude should not ever interfere with the PR process, that is how we gate AI's work + "Bash(gh pr create *)", + "Bash(gh pr edit *)", + "Bash(gh pr ready *)", + "Bash(gh pr review *)", + "Bash(gh pr merge *)", + "Bash(gh pr close *)", + "Bash(gh pr comment *)", + "Bash(gh pr update-branch *)", + // Destructive File Operations "Bash(chmod -R *)", "Bash(chown -R *)", diff --git a/template/.coderabbit.yaml b/template/.coderabbit.yaml index dd08ed4c8..b21d7b5cb 100644 --- a/template/.coderabbit.yaml +++ b/template/.coderabbit.yaml @@ -13,6 +13,8 @@ reviews: instructions: "These files came from a vendor and we're not allowed to change them. Refer to it if you need to understand how the main code interacts with it, but do not make comments about it." - path: "**/*.py" instructions: "Check the `ruff.toml` and `ruff-test.toml` for linting rules we've explicitly disabled and don't suggest changes to please conventions we've disabled. Do not express concerns about ruff rules; a pre-commit hook already runs a ruff check. Do not warn about unnecessary super().__init__() calls; pyright prefers those to be present. Do not warn about missing type hints; a pre-commit hook already checks for that." + - path: "**/.copier-answers.yml" + instructions: "Do not comment about the `_commit` value needing to be a clean release tag. A CI job will fail if that is not the case." tools: eslint: # when the code contains typescript, eslint will be run by pre-commit, and coderabbit often generates false positives enabled: false diff --git a/template/.devcontainer/manual-setup-deps.py b/template/.devcontainer/manual-setup-deps.py index 6f6fe0d8e..19a1c15ef 100644 --- a/template/.devcontainer/manual-setup-deps.py +++ b/template/.devcontainer/manual-setup-deps.py @@ -11,6 +11,7 @@ REPO_ROOT_DIR = Path(__file__).parent.parent.resolve() ENVS_CONFIG = REPO_ROOT_DIR / ".devcontainer" / "envs.json" +PULUMI_CLI_INSTALL_SCRIPT = REPO_ROOT_DIR / ".devcontainer" / "install-pulumi-cli.sh" UV_PYTHON_ALREADY_CONFIGURED = "UV_PYTHON" in os.environ parser = argparse.ArgumentParser(description="Manual setup for dependencies in the repo") _ = parser.add_argument( @@ -44,6 +45,12 @@ default=False, help="Allow uv to install new versions of Python on the fly. This is typically only needed when instantiating the copier template.", ) +_ = parser.add_argument( + "--skip-installing-pulumi-cli", + action="store_true", + default=False, + help="Do not install the Pulumi CLI even if the lock file references it", +) class PackageManager(str, enum.Enum): @@ -127,6 +134,22 @@ def main(): check=True, env=uv_env, ) + if ( + not generate_lock_file_only + and not args.skip_installing_pulumi_cli + and platform.system() == "Linux" + and env.lock_file.exists() + and '"pulumi"' in env.lock_file.read_text() + ): + if not PULUMI_CLI_INSTALL_SCRIPT.exists(): + print( + f"Pulumi CLI install script not found at {PULUMI_CLI_INSTALL_SCRIPT}, skipping Pulumi CLI installation" + ) + else: + _ = subprocess.run( + ["sh", str(PULUMI_CLI_INSTALL_SCRIPT), str(env.lock_file)], + check=True, + ) elif env.package_manager == PackageManager.PNPM: pnpm_command = ["pnpm", "install", "--dir", str(env.path)] if env_check_lock: diff --git a/template/.github/actions/install_deps/action.yml b/template/.github/actions/install_deps/action.yml index 0cedd63a3..7e22d8410 100644 --- a/template/.github/actions/install_deps/action.yml +++ b/template/.github/actions/install_deps/action.yml @@ -44,6 +44,11 @@ inputs: description: Whether to skip updating the hash when running manual-setup-deps.py default: true required: false + skip-installing-pulumi-cli: + type: boolean + description: Whether to skip installing the Pulumi CLI even if the lock file references it + default: false + required: false runs: @@ -83,5 +88,5 @@ runs: - name: Install dependencies # the funky syntax is github action ternary if: ${{ inputs.install-deps }} - run: python .devcontainer/manual-setup-deps.py ${{ inputs.python-version == 'notUsing' && '--no-python' || '' }} ${{ inputs.node-version == 'notUsing' && '--no-node' || '' }} ${{ inputs.skip-updating-devcontainer-hash && '--skip-updating-devcontainer-hash' || '' }} + run: python .devcontainer/manual-setup-deps.py ${{ inputs.python-version == 'notUsing' && '--no-python' || '' }} ${{ inputs.node-version == 'notUsing' && '--no-node' || '' }} ${{ inputs.skip-updating-devcontainer-hash && '--skip-updating-devcontainer-hash' || '' }} ${{ inputs.skip-installing-pulumi-cli && '--skip-installing-pulumi-cli' || '' }} shell: pwsh diff --git a/template/.github/workflows/ci.yaml.jinja b/template/.github/workflows/ci.yaml.jinja index e206ef99b..65c67882b 100644 --- a/template/.github/workflows/ci.yaml.jinja +++ b/template/.github/workflows/ci.yaml.jinja @@ -13,15 +13,17 @@ env: permissions: id-token: write # needed to assume OIDC roles (e.g. for downloading from CodeArtifact) - contents: write # needed for mutex, and updating dependabot branches - statuses: write # needed for updating status on Dependabot PRs + contents: read # need to explicitly provide this whenever defining permissions because the default value is 'none' for anything not explicitly set when permissions are defined jobs: get-values: uses: ./.github/workflows/get-values.yaml + permissions: + contents: write # needed for updating dependabot branches check-skip-duplicate: runs-on: {% endraw %}{{ gha_linux_runner }}{% raw %} + timeout-minutes: {% endraw %}{{ gha_short_timeout_minutes }}{% raw %} permissions: contents: read pull-requests: read # needed to check if PR exists for current branch @@ -42,6 +44,9 @@ jobs: if: needs.check-skip-duplicate.outputs.should-run == 'true' name: Pre-commit uses: ./.github/workflows/pre-commit.yaml + permissions: + contents: write # needed for mutex + id-token: write # needed to assume OIDC roles (e.g. for downloading from CodeArtifact) with: python-version: {% endraw %}{{ python_version }}{% raw %} setup-node: true diff --git a/template/.github/workflows/pre-commit.yaml b/template/.github/workflows/pre-commit.yaml index ffeb94851..fbdeb8605 100644 --- a/template/.github/workflows/pre-commit.yaml +++ b/template/.github/workflows/pre-commit.yaml @@ -50,6 +50,7 @@ jobs: python-version: ${{ inputs.python-version }} node-version: ${{ inputs.node-version }} skip-installing-ssm-plugin-manager: true + skip-installing-pulumi-cli: true - name: Set up mutex # Github concurrency management is horrible, things get arbitrarily cancelled if queued up. So using mutex until github fixes itself. When multiple jobs are modifying cache at once, weird things can happen. possible issue is https://github.com/actions/toolkit/issues/658 if: ${{ runner.os != 'Windows' }} # we're just gonna have to YOLO on Windows, because this action doesn't support it yet https://github.com/ben-z/gh-action-mutex/issues/14 diff --git a/template/AGENTS.md b/template/AGENTS.md index f40f69b61..f294f8339 100644 --- a/template/AGENTS.md +++ b/template/AGENTS.md @@ -19,24 +19,32 @@ ## Testing -- Always run tests with an explicit path (e.g. uv run pytest tests/unit) — test runners discover all types by default. +- Always run tests with an explicit path (e.g. uv run pytest tests/unit) — test runners discover all types (unit, integration, E2E...) by default. +- When iterating on a single test, run that test in isolation first and confirm it is in the expected state (red or green) before widening to the full suite. Use the most targeted invocation available: a specific test function for Python (e.g. `uv run pytest path/to/test.py::test_name --no-cov`) or a file path and name filter for TypeScript (e.g. `pnpm test-unit -- path/to/test.spec.ts -t "test name" --no-coverage`). Only run the full suite once the target test behaves as expected. - Test coverage requirements are usually at 100%, so when running a subset of tests, always disable test coverage to avoid the test run failing for insufficient coverage. - Avoid magic values in comparisons in tests in all languages (like ruff rule PLR2004 specifies) - Prefer using random values in tests rather than arbitrary ones (e.g. the faker library, uuids, random.randint) when possible. For enums, pick randomly rather than hardcoding one value. - Avoid loops in tests — assert each item explicitly so failures pinpoint the exact element. When verifying a condition across all items in a collection, collect the violations into a list and assert it's empty (e.g., assert [x for x in items if bad_condition(x)] == []). -- Key `data-testid` selectors off unique IDs (e.g. UUIDs), not human-readable names which may collide or change. +- When a test's final assertion is an absence (e.g., element is `null`, list is empty, modal is closed), include a prior presence assertion confirming the expected state existed before the action that removed it. A test whose only assertion is an absence check can pass vacuously if setup silently failed. +- When asserting a mock or spy was called with specific arguments, always constrain as tightly as possible. In order of preference: (1) assert called exactly once with those args (`assert_called_once_with` in Python, `toHaveBeenCalledExactlyOnceWith` in Vitest/Jest); (2) if multiple calls are expected, assert the total call count and use a positional or last-call assertion (`nthCalledWith`, `lastCalledWith` / `assert_has_calls` with `call_args_list[n]`); (3) plain "called with at any point" (`toHaveBeenCalledWith`, `assert_called_with`) is a last resort only when neither the call count nor the call order can reasonably be constrained. ### Python Testing -- When using `mocker.spy` on a class-level method (including inherited ones), the spy records the unbound call, so assertions need `ANY` as the first argument to match self: `spy.assert_called_once_with(ANY, expected_arg)` +- When using `mocker.spy` on a class-level method (including inherited ones), the spy records the unbound call, so assertions need `ANY` as the first argument to match self: `spy.assert_called_once_with(ANY, expected_arg)` - Before writing new mock/spy helpers, check the `tests/unit/` folder for pre-built helpers in files like `fixtures.py` or `*mocks.py` - When a test needs a fixture only for its side effects (not its return value), use `@pytest.mark.usefixtures(fixture_name.__name__)` instead of adding an unused parameter with a noqa comment - Use `__name__` instead of string literals when referencing functions/methods (e.g., `mocker.patch.object(MyClass, MyClass.method.__name__)`, `pytest.mark.usefixtures(my_fixture.__name__)`). This enables IDE refactoring tools to catch renames. - When using the faker library, prefer the pytest fixture (provided by the faker library) over instantiating instances of Faker. +- **Choosing between cassettes and mocks:** At the layer that directly wraps an external API or service, strongly prefer VCR cassette-recorded interactions (via pytest-recording/vcrpy) — they capture real HTTP traffic and verify the wire format, catching integration issues that mocks would miss. At layers above that (e.g. business logic, route handlers), mock the wrapper layer instead (e.g. `mocker.patch.object(ThresholdsRepository, ...)`) — there is no value in re-testing the HTTP interaction from higher up. - **Never hand-write VCR cassette YAML files.** Cassettes must be recorded from real HTTP interactions by running the test once with `--record-mode=once` against a live external service: `uv run pytest --record-mode=once --no-cov`. The default mode is `none` — a missing cassette will cause an error, which is expected until recorded. - **Never hand-edit syrupy snapshot files.** Snapshots are auto-generated — to create or update them, run `uv run pytest --snapshot-update --no-cov`. A missing snapshot causes the test to fail, which is expected until you run with `--snapshot-update`. When a snapshot mismatch occurs, fix the code if the change was unintentional; run `--snapshot-update` if it was intentional. - **Never hand-write or hand-edit pytest-reserial `.jsonl` recording files.** Recordings must be captured from real serial port traffic by running the test with `--record` while the device is connected: `uv run pytest --record --no-cov`. The default mode replays recordings — a missing recording causes an error, which is expected until recorded against a live device. +### Frontend Testing + +- Key `data-testid` selectors off unique IDs (e.g. UUIDs), not human-readable names which may collide or change. +- In DOM-based tests, scope queries to the tightest relevant container. Only query `document` or `document.body` directly to find the top-level portal/popup element (e.g. a Reka UI dialog via `[role="dialog"][data-state="open"]`); all further queries should run on that element, not on `document.body` again. + ## FastAPI - Use `fastapi.status` constants (e.g., `status.HTTP_204_NO_CONTENT`) instead of raw integers for status codes - All HTTP request and response payloads must use camelCase field names in JSON. Use Pydantic's `alias_generator=to_camel` with `populate_by_name=True` on models so that Python code uses snake_case internally while the wire format uses camelCase. @@ -57,7 +65,8 @@ - For frontend tests, run commands via `pnpm` scripts from `frontend/package.json` — never invoke tools directly (not pnpm exec , npx , etc.). ✅ pnpm test-unit ❌ pnpm vitest ... or npx vitest ... - For linting and type-checking, prefer `pre-commit run ` over invoking tools directly — this matches the permission allow-list and mirrors what CI runs. Key hook IDs: `typescript-check`, `eslint`, `pyright`, `ruff`, `ruff-format`. - Never rely on IDE diagnostics for ruff warnings — the IDE may not respect the project's ruff.toml config. Run `pre-commit run ruff -a` to get accurate results. -- When running terminal commands, execute exactly one command per tool call. Do not chain commands with &&, ||, ;, or & — this prohibition has no exceptions, even for `cd && ...` patterns. Use absolute paths instead of `cd` to avoid needing to chain. Pipes (|) are allowed for output transformation (e.g., head, tail, grep). If two sequential commands are needed, run them in separate tool calls. Chained commands break the permission allow-list matcher and cause unnecessary permission prompts +- When running terminal commands, execute exactly one command per tool call. Do not chain commands with &&, ||, ;, or & — this prohibition has no exceptions, even for `cd && ...` patterns. Use `cd` to change to the directory you want before running the command, avoiding the need to chain. Pipes (|) are allowed for output transformation (e.g., head, tail, grep). If two sequential commands are needed, run them in separate tool calls. Chained commands break the permission allow-list matcher and cause unnecessary permission prompts +- Never use `pnpm --prefix ` or `uv --directory ` to target a different directory — these flags break the permission allow-list matcher the same way chained `cd &&` commands do. Instead, rely on the working directory already being correct (the cwd persists between Bash tool calls), or issue a plain `cd ` as a separate prior tool call to reposition before running the command. - Never use backslash line continuations in shell commands — always write the full command on a single line. Backslashes break the permission allow-list matcher. - **Never manually edit files in any `generated/` folder.** These files are produced by codegen tooling (typically Kiota) and any manual changes will be overwritten. If a generated file needs to change, update the source (e.g. the OpenAPI schema) and re-run the generator. From c62c6920a9a032b0a073c3a2e363e0a9043d3391 Mon Sep 17 00:00:00 2001 From: Eli Fine Date: Tue, 31 Mar 2026 20:52:41 +0000 Subject: [PATCH 2/4] build-perms --- template/.github/workflows/ci.yaml.jinja | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/template/.github/workflows/ci.yaml.jinja b/template/.github/workflows/ci.yaml.jinja index 65c67882b..b22ed4160 100644 --- a/template/.github/workflows/ci.yaml.jinja +++ b/template/.github/workflows/ci.yaml.jinja @@ -133,6 +133,8 @@ jobs: {% endraw %}{% if push_to_ecr %}{% raw %} push-role-name: {% endraw %}{{ frontend_ecr_push_role_name }}{% endif %}{% else %}{% raw %} timeout-minutes: {% endraw %}{{ gha_medium_timeout_minutes }}{% raw %} runs-on: {% endraw %}{{ gha_linux_runner }}{% raw %} + permissions: + contents: write # needed for mutex steps: - name: Checkout code uses: actions/checkout@{% endraw %}{{ gha_checkout }}{% raw %} @@ -179,6 +181,8 @@ jobs: - build-frontend - check-skip-duplicate if: needs.check-skip-duplicate.outputs.should-run == 'true' + permissions: + contents: write # needed for mutex strategy: matrix: os: From a0c66e978ce33e956ea93d3a690885927bf1127d Mon Sep 17 00:00:00 2001 From: Eli Fine Date: Tue, 31 Mar 2026 20:57:02 +0000 Subject: [PATCH 3/4] perms --- template/.github/workflows/ci.yaml.jinja | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/template/.github/workflows/ci.yaml.jinja b/template/.github/workflows/ci.yaml.jinja index b22ed4160..80ee81e5f 100644 --- a/template/.github/workflows/ci.yaml.jinja +++ b/template/.github/workflows/ci.yaml.jinja @@ -124,6 +124,9 @@ jobs: - check-skip-duplicate if: needs.check-skip-duplicate.outputs.should-run == 'true' {% endraw %}{% if not deploy_as_executable %}{% raw %} uses: ./.github/workflows/build-docker-image.yaml + permissions: + contents: write # needed for mutex + id-token: write # needed to assume OIDC roles (e.g. for downloading from CodeArtifact) with: context: ./frontend save-as-artifact: true @@ -133,8 +136,6 @@ jobs: {% endraw %}{% if push_to_ecr %}{% raw %} push-role-name: {% endraw %}{{ frontend_ecr_push_role_name }}{% endif %}{% else %}{% raw %} timeout-minutes: {% endraw %}{{ gha_medium_timeout_minutes }}{% raw %} runs-on: {% endraw %}{{ gha_linux_runner }}{% raw %} - permissions: - contents: write # needed for mutex steps: - name: Checkout code uses: actions/checkout@{% endraw %}{{ gha_checkout }}{% raw %} @@ -166,6 +167,9 @@ jobs: - check-skip-duplicate if: needs.check-skip-duplicate.outputs.should-run == 'true' uses: ./.github/workflows/build-docker-image.yaml + permissions: + contents: write # needed for mutex + id-token: write # needed to assume OIDC roles (e.g. for downloading from CodeArtifact) with: context: ./backend save-as-artifact: true @@ -181,8 +185,6 @@ jobs: - build-frontend - check-skip-duplicate if: needs.check-skip-duplicate.outputs.should-run == 'true' - permissions: - contents: write # needed for mutex strategy: matrix: os: From 6b7fccdf7732349a9fc09ae8d78ff3f35ff57ce7 Mon Sep 17 00:00:00 2001 From: Eli Fine Date: Wed, 1 Apr 2026 10:04:34 +0000 Subject: [PATCH 4/4] more cI --- template/.github/workflows/ci.yaml.jinja | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/template/.github/workflows/ci.yaml.jinja b/template/.github/workflows/ci.yaml.jinja index 80ee81e5f..76dced866 100644 --- a/template/.github/workflows/ci.yaml.jinja +++ b/template/.github/workflows/ci.yaml.jinja @@ -449,7 +449,10 @@ jobs: - get-values - check-skip-duplicate - lint - - unit-test-frontend{% endraw %}{% if create_docker_image_tar_artifact %}{% raw %} + - unit-test-frontend + - build-frontend{% endraw %}{% if has_backend %}{% raw %} + - unit-test-backend + - build-backend{% endraw %}{% endif %}{% raw %}{% endraw %}{% if create_docker_image_tar_artifact %}{% raw %} - package-images{% endraw %}{% endif %}{% raw %} - test-compiled-frontend{% endraw %}{% if is_circuit_python_driver %}{% raw %} - package-firmware{% endraw %}{% endif %}{% raw %}{% endraw %}{% if run_backend_e2e_in_ci %}{% raw %} @@ -467,7 +470,10 @@ jobs: if [[ ! "${{ needs.get-values.result }}" =~ $success_pattern ]] || [[ ! "${{ needs.check-skip-duplicate.result }}" =~ $success_pattern ]] || [[ ! "${{ needs.lint.result }}" =~ $success_pattern ]] || - [[ ! "${{ needs.unit-test-frontend.result }}" =~ $success_pattern ]] ||{% endraw %}{% if create_docker_image_tar_artifact %}{% raw %} + [[ ! "${{ needs.unit-test-frontend.result }}" =~ $success_pattern ]] || + [[ ! "${{ needs.build-frontend.result }}" =~ $success_pattern ]] ||{% endraw %}{% if has_backend %}{% raw %} + [[ ! "${{ needs.unit-test-backend.result }}" =~ $success_pattern ]] || + [[ ! "${{ needs.build-backend.result }}" =~ $success_pattern ]] ||{% endraw %}{% endif %}{% raw %}{% endraw %}{% if create_docker_image_tar_artifact %}{% raw %} [[ ! "${{ needs.package-images.result }}" =~ $success_pattern ]] ||{% endraw %}{% endif %}{% raw %} [[ ! "${{ needs.test-compiled-frontend.result }}" =~ $success_pattern ]] ||{% endraw %}{% if is_circuit_python_driver %}{% raw %} [[ ! "${{ needs.package-firmware.result }}" =~ $success_pattern ]] ||{% endraw %}{% endif %}{% raw %}{% endraw %}{% if run_backend_e2e_in_ci %}{% raw %}