mirror of
https://github.com/invoke-ai/InvokeAI.git
synced 2026-10-12 02:16:43 +00:00
feat(agents): add codebase agent instructions
also updates gitignore to exclude planning files
This commit is contained in:
Josh Corbett
+10
-37
@@ -1,38 +1,11 @@
|
||||
# Agent Instructions
|
||||
# CI and contributions
|
||||
|
||||
## Package Management
|
||||
|
||||
This repository has two independently managed TypeScript/React frontends, both using **pnpm** exclusively:
|
||||
|
||||
- `invokeai/frontend/web/`
|
||||
- `invokeai/frontend/webv2/`
|
||||
|
||||
- ✅ Use `pnpm` commands for both frontends.
|
||||
- ✅ Run commands against the intended frontend with `pnpm -C <directory> ...`.
|
||||
- ❌ Never use `npm` or `yarn`.
|
||||
- ❌ Never create or use `package-lock.json` or `yarn.lock`.
|
||||
- ✅ Each frontend owns its own `pnpm-lock.yaml`.
|
||||
|
||||
Typical commands for the established frontend:
|
||||
|
||||
- `pnpm -C invokeai/frontend/web install`
|
||||
- `pnpm -C invokeai/frontend/web build`
|
||||
- `pnpm -C invokeai/frontend/web lint:tsc`
|
||||
- `pnpm -C invokeai/frontend/web lint:dpdm`
|
||||
- `pnpm -C invokeai/frontend/web lint:eslint`
|
||||
- `pnpm -C invokeai/frontend/web lint:prettier`
|
||||
|
||||
Typical commands for the Workbench frontend:
|
||||
|
||||
- `pnpm -C invokeai/frontend/webv2 install`
|
||||
- `pnpm -C invokeai/frontend/webv2 build`
|
||||
- `pnpm -C invokeai/frontend/webv2 format:check`
|
||||
- `pnpm -C invokeai/frontend/webv2 lint:oxc`
|
||||
- `pnpm -C invokeai/frontend/webv2 lint:tsc`
|
||||
- `pnpm -C invokeai/frontend/webv2 test:all`
|
||||
|
||||
## Project Structure
|
||||
|
||||
- Backend: Python in `invokeai/`
|
||||
- Established frontend: TypeScript/React in `invokeai/frontend/web/`
|
||||
- Workbench frontend: TypeScript/React in `invokeai/frontend/webv2/`
|
||||
- Shared engineering and package rules live in the root `AGENTS.md`. Read the affected package's guidance before changing checks.
|
||||
- Preserve supported events: pull requests, main pushes, merge groups, manual dispatch, and reusable workflow calls. Never assume `github.base_ref` is populated outside a PR event.
|
||||
- Include the workflow itself and relevant shared actions/configuration in change detection. Test-only and tooling-only changes must reach their owning checks; skipped work must not hide required validation.
|
||||
- Use existing Node/Python/pnpm/uv versions and lockfiles. Keep dependency installs reproducible and respect hardware/platform matrices. Preserve pinned action revisions where used.
|
||||
- Prefer package completion commands over reproducing their internals in YAML. Webv2's `pnpm check:release` includes architecture, tests, performance/build, project files, and accessibility; install Chromium and required Linux dependencies first.
|
||||
- Preserve diagnostic artifacts on failure with `always()` where appropriate. Keep generated review/performance artifacts out of Git. Distinguish real checks from skipped or unavailable checks.
|
||||
- Keep hooks aligned with CI's Ruff version/configuration. Do not add formatter rewrites to validation or silently relax failures/budgets to make a new gate green.
|
||||
- PR descriptions lead with the problem and resulting behavior. Include actual checks, material review findings resolved, and relevant UI evidence, compatibility details, or performance measurements. Keep summaries short; do not attach planning logs.
|
||||
- Workflow files add checks but do not configure hosted branch protection or install local hooks. Do not claim either happened without verification.
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -1,6 +1,6 @@
|
||||
## Summary
|
||||
|
||||
<!--A description of the changes in this PR. Include the kind of change (fix, feature, docs, etc), the "why" and the "how". Screenshots or videos are useful for frontend changes.-->
|
||||
<!-- Lead with the problem and resulting behavior. Keep this short; show a concrete before/after when useful. -->
|
||||
|
||||
## Related Issues / Discussions
|
||||
|
||||
@@ -8,16 +8,22 @@
|
||||
|
||||
## QA Instructions
|
||||
|
||||
<!--WHEN APPLICABLE: Describe how you have tested the changes in this PR. Provide enough detail that a reviewer can reproduce your tests.-->
|
||||
<!-- List actual commands/results and relevant reproduction steps. State skipped, failing, or unavailable checks honestly. Include screenshots/video for changed UI and before/after measurements for material performance claims. -->
|
||||
|
||||
## Merge Plan
|
||||
## Review
|
||||
|
||||
<!--WHEN APPLICABLE: Large PRs, or PRs that touch sensitive things like DB schemas, may need some care when merging. For example, a careful rebase by the change author, timing to not interfere with a pending release, or a message to contributors on discord after merging.-->
|
||||
<!-- Summarize material findings resolved and the final blocker-only review result. For agent-assisted work, identify independent review focuses or disclose the self-review fallback. Do not attach review transcripts or work logs. -->
|
||||
|
||||
## Compatibility / Rollout
|
||||
|
||||
<!-- When applicable: persisted-data migrations, API/generated-artifact compatibility, deployment ordering, and recovery considerations. Omit this section when unnecessary. -->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] _The PR has a short but descriptive title, suitable for a changelog_
|
||||
- [ ] _Tests added / updated (if applicable)_
|
||||
- [ ] _❗Changes to a redux slice have a corresponding migration_
|
||||
- [ ] _Meaningful regression coverage added / updated where needed; obsolete tests/code removed_
|
||||
- [ ] _Persisted-state and API changes include required migrations / compatibility validation_
|
||||
- [ ] _Relevant performance/efficiency opportunities considered; material claims have evidence_
|
||||
- [ ] _Material review findings resolved and relevant checks rerun_
|
||||
- [ ] _Documentation added / updated (if applicable)_
|
||||
- [ ] _Updated `What's New` copy (if doing a release after this PR)_
|
||||
|
||||
@@ -40,17 +40,6 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
|
||||
- name: Fail if package-lock.json is added/modified (pnpm only)
|
||||
shell: bash
|
||||
working-directory: .
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git fetch --no-tags --prune --depth=1 origin "${{ github.base_ref }}"
|
||||
if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -E '(^|/)package-lock\.json$'; then
|
||||
echo "::error::package-lock.json was added or modified. This repo uses pnpm only."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: check for changed frontend files
|
||||
if: ${{ inputs.always_run != true }}
|
||||
id: changed-files
|
||||
@@ -63,6 +52,8 @@ jobs:
|
||||
with:
|
||||
files_yaml: |
|
||||
frontend:
|
||||
- '.github/workflows/frontend-checks.yml'
|
||||
- '.github/actions/install-frontend-deps/**'
|
||||
- 'invokeai/frontend/web/**'
|
||||
|
||||
- name: install dependencies
|
||||
@@ -110,6 +101,8 @@ jobs:
|
||||
with:
|
||||
files_yaml: |
|
||||
webv2:
|
||||
- '.github/workflows/frontend-checks.yml'
|
||||
- '.github/actions/install-frontend-deps/**'
|
||||
- 'invokeai/frontend/webv2/**'
|
||||
|
||||
- name: install dependencies
|
||||
|
||||
@@ -52,6 +52,8 @@ jobs:
|
||||
with:
|
||||
files_yaml: |
|
||||
frontend:
|
||||
- '.github/workflows/frontend-tests.yml'
|
||||
- '.github/actions/install-frontend-deps/**'
|
||||
- 'invokeai/frontend/web/**'
|
||||
|
||||
- name: install dependencies
|
||||
@@ -65,7 +67,7 @@ jobs:
|
||||
|
||||
frontend-webv2-tests:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15 # Includes browser suites, performance sampling, and project-file journeys.
|
||||
timeout-minutes: 20 # Includes browser suites, performance, project files, and accessibility.
|
||||
defaults:
|
||||
run:
|
||||
working-directory: invokeai/frontend/webv2
|
||||
@@ -80,6 +82,7 @@ jobs:
|
||||
files_yaml: |
|
||||
webv2:
|
||||
- '.github/workflows/frontend-tests.yml'
|
||||
- '.github/actions/install-frontend-deps/**'
|
||||
- 'invokeai/frontend/webv2/**'
|
||||
|
||||
- name: install dependencies
|
||||
@@ -90,12 +93,14 @@ jobs:
|
||||
|
||||
- name: install Chromium
|
||||
if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
|
||||
run: 'pnpm exec playwright install chromium'
|
||||
run: 'pnpm exec playwright install --with-deps chromium'
|
||||
shell: bash
|
||||
|
||||
- name: architecture completion gates
|
||||
- name: release completion gates
|
||||
if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
|
||||
run: 'pnpm check:architecture'
|
||||
run: |
|
||||
mkdir -p artifacts/accessibility
|
||||
pnpm check:release 2>&1 | tee artifacts/accessibility/release-check.log
|
||||
shell: bash
|
||||
|
||||
- name: upload architecture review artifacts
|
||||
@@ -106,4 +111,5 @@ jobs:
|
||||
path: |
|
||||
invokeai/frontend/webv2/artifacts/architecture
|
||||
invokeai/frontend/webv2/artifacts/architecture-performance
|
||||
invokeai/frontend/webv2/artifacts/accessibility
|
||||
if-no-files-found: ignore
|
||||
|
||||
@@ -199,5 +199,12 @@ installer/InvokeAI-Installer/
|
||||
.claude/
|
||||
.superpowers/
|
||||
|
||||
# Temporary agent planning artifacts.
|
||||
**/.agents/plans/
|
||||
**/.codex/plans/
|
||||
**/.claude/plans/
|
||||
**/docs/plans/
|
||||
**/docs/superpowers/
|
||||
|
||||
# Weblate configuration file
|
||||
weblate.ini
|
||||
|
||||
+7
-14
@@ -2,25 +2,18 @@
|
||||
repos:
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: black
|
||||
name: black
|
||||
- id: ruff-check
|
||||
name: ruff check
|
||||
stages: [pre-commit]
|
||||
language: system
|
||||
entry: black
|
||||
entry: uv tool run [email protected] check --force-exclude
|
||||
types: [python]
|
||||
|
||||
- id: flake8
|
||||
name: flake8
|
||||
- id: ruff-format
|
||||
name: ruff format check
|
||||
stages: [pre-commit]
|
||||
language: system
|
||||
entry: flake8
|
||||
types: [python]
|
||||
|
||||
- id: isort
|
||||
name: isort
|
||||
stages: [pre-commit]
|
||||
language: system
|
||||
entry: isort
|
||||
entry: uv tool run [email protected] format --check --force-exclude
|
||||
types: [python]
|
||||
|
||||
- id: uvlock
|
||||
@@ -29,4 +22,4 @@ repos:
|
||||
language: system
|
||||
entry: uv lock
|
||||
files: ^pyproject\.toml$
|
||||
pass_filenames: false
|
||||
pass_filenames: false
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Working on InvokeAI
|
||||
|
||||
## Communication
|
||||
|
||||
- Speak plainly and matter-of-factly. Assume readers benefit from short, skimmable updates; avoid filler, ceremony, and repeated status summaries.
|
||||
- Ask only when a decision cannot be inferred safely from the repository or request. Continue authorized work without repeated permission requests.
|
||||
- Lead with outcomes, blockers, and concrete evidence. Distinguish verified results from assumptions and checks you could not run.
|
||||
|
||||
## Find the right owner
|
||||
|
||||
Before editing, read the applicable `AGENTS.md` files along each target path, even when starting at the repository root. Scoped guidance adds to these rules. `CLAUDE.md` files only import their sibling `AGENTS.md`; keep policy canonical here.
|
||||
|
||||
| Area | Guidance and source of truth |
|
||||
| --- | --- |
|
||||
| Active frontend | [webv2/AGENTS.md](invokeai/frontend/webv2/AGENTS.md), its `ARCHITECTURE.md` and executable architecture policy |
|
||||
| API, services, invocations | [app/AGENTS.md](invokeai/app/AGENTS.md) |
|
||||
| Inference and model management | [backend/AGENTS.md](invokeai/backend/AGENTS.md) |
|
||||
| Python tests | [tests/AGENTS.md](tests/AGENTS.md); also read guidance for the production code under test |
|
||||
| Legacy frontend and generated API artifacts | [web/AGENTS.md](invokeai/frontend/web/AGENTS.md) |
|
||||
| CI and contribution tooling | [.github/AGENTS.md](.github/AGENTS.md) |
|
||||
| Documentation | `docs/README.md` and `docs/package.json`; keep documentation about the implemented product current |
|
||||
|
||||
Ordinary frontend features and fixes target **webv2**. The backend serves it when launched with `--webv2`; a default launch still selects legacy web. Verify the build and launch target when investigating UI behavior. Legacy web still owns generated OpenAPI/type artifacts.
|
||||
|
||||
## Engineering standard
|
||||
|
||||
- Produce correct, functional, efficient, maintainable, DRY, production-quality code. Inspect implementations, callers, contracts, and existing tests before designing changes.
|
||||
- Define the observable outcome and relevant validation. For bugs, establish a reproduction or failing behavioral test where feasible, then address the root cause. Reconsider the design when narrow fixes keep accumulating.
|
||||
- Consider edge cases, failure modes, data lifecycle, and operational limits. Keep ownership explicit and concentrate behavior behind small interfaces.
|
||||
- Every function, abstraction, dependency, fallback, and test must earn its place. Avoid pass-through wrappers, speculative extensibility, redundant validation, unnecessary configuration, and one-use abstractions that hide no meaningful complexity.
|
||||
- Small adapters are useful when they translate contracts, isolate dependencies, or own a lifecycle. Extract shared behavior when it prevents drift or simplifies callers; do not abstract merely because code looks similar.
|
||||
- Remove code, tests, and scaffolding made obsolete by the change. Preserve unrelated work and avoid drive-by rewrites.
|
||||
- Comment only non-obvious intent, constraints, or trade-offs. Do not narrate code.
|
||||
- Tests should protect meaningful behavior and catch a plausible regression. Avoid trivial constant/type/re-export assertions, expected values recomputed by the implementation's algorithm, and mocks that only verify internal choreography.
|
||||
- Test through the interface that owns the behavior. Prefer real lightweight dependencies and isolated fixtures; use doubles for expensive or external systems. Choose regression coverage for value, not test counts.
|
||||
- Keep dependencies and lockfile changes intentional. Do not weaken assertions, gates, architecture policy, or performance budgets just to pass. Explain existing failures and verification limits.
|
||||
- Keep durable architecture/reference documentation aligned with implemented behavior. Installed skills are optional helpers, not prerequisites; adapt their principles to this repository's stack and interfaces. Do not import personal paths or generic skill ceremony into the workflow.
|
||||
|
||||
## Performance and efficiency
|
||||
|
||||
- Actively inspect the PR's affected hot paths and immediate callers for efficiency wins: repeated work, unnecessary renders/subscriptions, request waterfalls, excess queries, serialization/copies, unbounded collections, and retained resources.
|
||||
- For inference, consider device transfers, dtype conversions, peak memory, model/cache lifetimes, and unnecessary synchronization.
|
||||
- Implement clear, low-risk improvements within the PR's scope. Larger optimizations must directly serve its outcome; mention unrelated opportunities briefly without expanding the PR.
|
||||
- Measure nontrivial optimizations and performance claims using existing budgets, representative fixtures, query counts, profiling, or focused benchmarks. Report material before/after results and their limits.
|
||||
- Preserve correctness and clarity. Add caching, memoization, concurrency, or batching only with understood invalidation, lifetimes, ordering, and cost. Do not invent an optimization or benchmark to satisfy a checklist.
|
||||
|
||||
## Product quality
|
||||
|
||||
InvokeAI is a polished professional creative product. Maintain a first-class desktop experience: deliberate layouts, responsive interactions, cohesive controls, accessibility, and performance. Complete loading, empty, error, and recovery states. Verify changed interactions in the browser; automated checks do not establish visual quality by themselves.
|
||||
|
||||
## Milestones and code review rules
|
||||
|
||||
A milestone is one coherent, commit-ready unit of work. Before calling it commit-worthy:
|
||||
|
||||
1. Run relevant checks, then spawn three independent, read-only review subagents with distinct focuses: correctness/spec conformance; architecture/operational safety/performance/unnecessary complexity; and test value/gaps/product quality (including accessibility for UI changes).
|
||||
2. Give each reviewer the same fixed comparison base, acceptance criteria, and complete candidate changes, including staged, unstaged, and new files. Reviewers inspect independently and do not edit, commit, or recursively delegate reviews.
|
||||
3. Require concrete locations, impact, and a failure scenario or engineering cost. Material findings affect behavior, safety, maintainability, efficiency, or meaningful coverage; style preferences alone are not blockers.
|
||||
4. Resolve every material finding, add useful regression coverage, and rerun affected checks. Request final blocker-only review of the resulting candidate. Further edits invalidate the relevant review results.
|
||||
5. Do not call work commit-worthy with material findings or unexplained failing gates. Report what passed, what failed or was unavailable, and material remaining limitations.
|
||||
|
||||
If the environment cannot spawn subagents, perform separate self-review passes with the same focuses and explicitly disclose that independent review was unavailable. Never represent self-review as independent review. Delegating implementation is optional; use it for independently useful tasks with clear ownership.
|
||||
|
||||
## Commands and environments
|
||||
|
||||
- Use **pnpm 10**, never npm/yarn, for frontends and docs. Each package owns its lockfile. Use `pnpm -C <package> ...`; `.nvmrc` records the development Node version. Read the package scripts instead of assuming root Makefile frontend commands target webv2.
|
||||
- Use the existing Python environment and `uv.lock`. For a fresh test environment: `uv sync --locked --extra test`; do not replace a configured accelerator environment with a different backend as routine setup.
|
||||
- From the root: `uv tool run [email protected] check <paths>` and `uv tool run [email protected] format --check <paths>`. Python uses 120-column formatting and absolute imports. Respect configured vendored-code exclusions.
|
||||
- Run focused Python tests with `uv run --no-sync pytest <test-paths>`; the full CI suite is `uv run --no-sync pytest`. Slow tests are excluded by default; hardware validation is separate.
|
||||
- `uv run --no-sync mypy scripts/invokeai-web.py` is an additional diagnostic using the current exclusions, not an enforced CI gate. Do not describe it as comprehensive type coverage.
|
||||
- Choose checks by changed behavior. Broaden to the milestone's required gates before review; do not repeatedly rerun unchanged checks without a reason.
|
||||
- Install local hooks with `uv run --no-sync pre-commit install` after test dependencies are available. Hook installation is local to each checkout and is not implied by committing the configuration.
|
||||
|
||||
## Scratch files and repository hygiene
|
||||
|
||||
- Never commit task plans, work logs, investigation notes, review transcripts, or handoffs, regardless of filename. Use `.scratch/agents/<task>/` if persistence is useful; creating these files is optional.
|
||||
- Durable documentation of implemented architecture, decisions, APIs, and setup belongs in version control. Do not turn scratch logs into permanent docs merely to bypass this rule.
|
||||
- Ignore rules keep recognized scratch/planning paths out of ordinary staging; they do not prevent force-adds or remove files already tracked by Git.
|
||||
- Inspect the staged diff and new files for planning material, including unexpected filenames. Never force-add planning artifacts or introduce `package-lock.json`/`yarn.lock`.
|
||||
|
||||
## Commits
|
||||
|
||||
- Commit readiness does not itself authorize committing or pushing. Follow the request's existing authorization; do not add an automatic commit/push step to each subtask.
|
||||
- Use Conventional Commits with the shortest descriptive, skimmable subject that states the outcome.
|
||||
- Follow the subject with one to three short, factual lines summarizing material changes; use bullets when useful. Omit implementation narration and details already clear from the subject.
|
||||
- Leave authorship to the configured Git author. Do not add agent attribution or co-author trailers.
|
||||
@@ -1,13 +1 @@
|
||||
# Frontend work targets webv2
|
||||
|
||||
All frontend feature and bugfix work in this repo is done in
|
||||
**`invokeai/frontend/webv2`** — the frontend the running app actually serves.
|
||||
|
||||
`invokeai/frontend/web` is the legacy frontend: do not implement fixes or
|
||||
features there, and do not assume reported UI bugs live in it. The two use
|
||||
different DnD libraries (webv2: @dnd-kit; legacy web: pragmatic-drag-and-drop),
|
||||
different styling stacks, and different lint/test commands.
|
||||
|
||||
webv2 commands (run from `invokeai/frontend/webv2/`): `pnpm lint`, `pnpm test`,
|
||||
`pnpm run test:browser`. webv2 is git-tracked, so the usual branch + worktree
|
||||
workflow applies to it.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# Application backend
|
||||
|
||||
## Ownership and contracts
|
||||
|
||||
- API routers validate requests, enforce authentication/authorization, and map service errors to HTTP responses. Services own domain behavior; storage implementations own persistence. Keep reusable policy out of route handlers.
|
||||
- Inspect `api/dependencies.py`, the affected router, service base/default/storage implementations, and corresponding tests before changing a flow. Follow existing dependency and start/stop lifecycles rather than creating parallel global services.
|
||||
- Authorize access to every account-owned resource on the server. Preserve ownership filtering for queries, writes, events, exports, and recovery; a UI guard is insufficient.
|
||||
- Pydantic models, invocation fields/versions, HTTP DTOs, and socket events are contracts. Trace frontend and saved-workflow consumers before changing names, defaults, validation, or errors.
|
||||
- API changes may require regenerating `frontend/web/openapi.json` and `frontend/web/src/services/api/schema.ts` (under `invokeai/`) even when the feature UI lives in webv2. Never hand-edit generated output. Read the legacy frontend guidance for commands.
|
||||
|
||||
## Persistence and lifecycle
|
||||
|
||||
- Preserve atomicity, revision checks, idempotency, and explicit conflict behavior. Inspect migrations and old-record readers before changing stored data; add migration/compatibility tests when needed.
|
||||
- SQLite transactions are not automatically composable. Read `services/shared/sqlite/sqlite_database.py` and `services/project_records/project_records_sqlite.py`: nested service calls that open transactions can commit an outer operation prematurely. Keep multi-record writes under one transaction owner and pass its cursor where the design supports it.
|
||||
- Preserve project/account isolation, bounded document sizes, queue admission/receipt semantics, and lost-response retry safety. Do not silently discard recovery data or turn conflicting writes into last-write-wins saves.
|
||||
- Long-running work needs bounded concurrency, cancellation, appropriate timeouts/retries, and reliable cleanup of files, subprocesses, listeners, and task state. Avoid blocking the async server loop with CPU or blocking I/O work.
|
||||
- Preserve file/path validation, existing remote-fetch protections, and sanitized errors. Tests and debugging must not modify a user's real models, database, outputs, or credentials.
|
||||
|
||||
## Efficiency and verification
|
||||
|
||||
- Examine affected queries for repeated lookups, unnecessary full scans/materialization, missing bounds, and excessive serialization. Use representative data and query counts/measurements before adding caches or indexes.
|
||||
- Use real temporary SQLite storage for transaction, migration, revision, and ownership tests. Cover malformed input, cross-user access, cancellation, repeated requests, and partial failure when relevant; do not mock away the behavior being protected.
|
||||
- Tests normally live under `tests/app/` or the existing owning suite in `tests/`; read `tests/AGENTS.md`. Run focused pytest plus root Ruff checks. Broaden to relevant service/router/invocation suites for a milestone.
|
||||
- Graph execution changes should consult `services/shared/README.md` and test scheduling and invocation lifecycle through their owning interfaces.
|
||||
- Report API/schema generation results, migration validation, and unavailable integration/hardware checks honestly. Root mypy is an additional diagnostic, not an existing CI requirement.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,23 @@
|
||||
# Inference and model backend
|
||||
|
||||
## Design and resources
|
||||
|
||||
- Trace the caller, model loader/cache, tensor shapes, device/dtype handling, and cleanup before changing inference. Keep reusable model/inference policy here rather than in UI or API adapters.
|
||||
- Use existing device selection and model-management abstractions, including `util/devices.py`. Do not hardcode CUDA, GPU zero, or a dtype when CPU, MPS, ROCm, XPU, or multiple devices need to work.
|
||||
- Respect session/thread device ownership. Restore temporary model patches, device state, hooks, and allocations on success, cancellation, and exceptions. Avoid request-specific mutable process-wide state.
|
||||
- Keep model/cache lifetimes and working-memory estimates explicit. Bound queues, caches, downloads, batches, and temporary buffers; consider peak memory as well as throughput.
|
||||
- Preserve model format validation and loading safeguards. Respect vendored-code exclusions and upstream provenance; avoid unrelated formatting or rewrites in vendored modules.
|
||||
|
||||
## Performance
|
||||
|
||||
- Hunt for efficiency wins on the affected inference path: duplicate work, device transfers, dtype conversions, tensor copies, CPU/GPU synchronization, repeated loading, and retained tensors.
|
||||
- Use representative shapes, resolutions, batch sizes, and supported device paths. Measure material latency/throughput and peak-memory changes; distinguish cold loading/compilation from warmed inference.
|
||||
- Retain numerical correctness with appropriate tolerances and reproducible seeds where supported. A faster path is not an improvement if it changes output semantics, breaks cancellation, or shifts failures to larger inputs.
|
||||
- Do not add speculative kernels, caches, compilation, or concurrent execution without a demonstrated benefit and clear fallback/lifecycle behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
- Read `tests/AGENTS.md` and the relevant existing suites under `tests/backend/`, `tests/model_identification/`, or `tests/test_model_manager/`.
|
||||
- Use small CPU fixtures for logic where possible, plus targeted hardware checks for device-specific behavior. Test real tensor operations when mocks would hide shape, dtype, numerical, or memory errors.
|
||||
- Cover failure cleanup, unsupported configurations, boundary shapes, and cancellation where affected. Do not download large models or use the user's model/output directories as routine unit-test setup.
|
||||
- Run focused pytest and root Ruff checks. Record tested hardware, dtype, shapes, and measurements for material inference changes. Explicitly state untested platforms and model paths; CPU tests do not prove accelerator behavior.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,19 @@
|
||||
# Legacy frontend
|
||||
|
||||
Ordinary frontend feature and bugfix work targets `../webv2/`; read its guidance. Change legacy UI only when explicitly requested or a shared compatibility change requires it. The backend still selects legacy web without `--webv2`.
|
||||
|
||||
This package still owns `openapi.json`, generated `src/services/api/schema.ts`, and their generation tooling. Updating these for backend contract changes is expected and does not imply implementing the UI here.
|
||||
|
||||
## Commands
|
||||
|
||||
Run from this directory, with pnpm 10 and this package's lockfile:
|
||||
|
||||
- `pnpm lint`: legacy TypeScript, dependency-cycle, ESLint, Prettier, and unused-dependency checks.
|
||||
- `pnpm test:no-watch`: legacy Vitest suite; colocate meaningful tests using existing conventions.
|
||||
- `pnpm build`: legacy production build.
|
||||
- From an activated repository Python environment, `python ../../../scripts/generate_openapi_schema.py > openapi.json` then `pnpm exec prettier --write openapi.json` regenerates the schema.
|
||||
- From that same environment, `python ../../../scripts/generate_openapi_schema.py | pnpm typegen` regenerates frontend types. Use a shell with pipeline failure propagation and verify generator success; never hand-edit generated files.
|
||||
|
||||
Use root Ruff/pytest commands for associated Python changes. Do not apply webv2's Chakra version, @dnd-kit APIs, Oxc commands, or browser-test assumptions here. Preserve existing persisted-state migrations when changing legacy state behavior.
|
||||
|
||||
Shared review, scratch, performance, test-value, and commit rules apply. There is no mandatory work log, automatic commit, or requirement for named vendor-specific agents.
|
||||
@@ -1,39 +1 @@
|
||||
# Bash commands
|
||||
|
||||
All commands should be run from `<REPO_ROOT>/invokeai/frontend/web/`.
|
||||
|
||||
- `pnpm lint:prettier`: check formatting
|
||||
- `pnpm lint:eslint`: check for linting issues
|
||||
- `pnpm lint:knip`: check for unused dependencies
|
||||
- `pnpm lint:dpdm`: check for dependency cycles
|
||||
- `pnpm lint:tsc`: check for TypeScript issues
|
||||
- `pnpm lint`: run all checks
|
||||
- `pnpm fix`: automatically fix issues where possible
|
||||
- `pnpm test:no-watch`: run the test suite
|
||||
|
||||
# Writing Tests
|
||||
|
||||
This repo uses `vitest` for unit tests.
|
||||
|
||||
Tests should be colocated with the code they test, and should use the `.test.ts` suffix.
|
||||
|
||||
Tests do not need to be written for code that is trivial or has no logic (e.g. simple type definitions, re-exports, etc.). We currently do not do UI tests.
|
||||
|
||||
# Agents
|
||||
|
||||
- Use @agent-javascript-pro and @agent-typescript-pro for JavaScript and TypeScript code generation and assistance.
|
||||
- Use @frontend-developer for general frontend development tasks.
|
||||
|
||||
## Workflow
|
||||
|
||||
Split up tasks into smaller subtasks and handle them one at a time using an agent. Ensure each subtask is completed before moving on to the next.
|
||||
|
||||
Each agent should maintain a work log in a markdown file.
|
||||
|
||||
When an agent completes a task, it should:
|
||||
|
||||
1. Summarize the changes made.
|
||||
2. List any files that were added, modified, or deleted.
|
||||
3. Commit the changes with a descriptive commit message.
|
||||
|
||||
DO NOT PUSH ANY CHANGES TO THE REMOTE REPOSITORY.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
# Webv2
|
||||
|
||||
Read [ARCHITECTURE.md](ARCHITECTURE.md) before changing module ownership or interfaces. Read the affected owner-local README for lifecycle/persistence behavior. This is a React 19, Vite, Chakra UI 3, TanStack Query/Router, and @dnd-kit application; legacy web uses different libraries and commands.
|
||||
|
||||
## Ownership and state
|
||||
|
||||
- Follow `app -> workbench/features -> platform` and the executable policy in `src/architecture/`. App composes dependencies; Platform owns domain-neutral infrastructure; Features own domain behavior; Workbench owns the project aggregate, shell, and Canvas.
|
||||
- Import Features through their registered top-level public entries. Do not deep-import another owner's implementation to follow generic advice against barrel imports. Pure cores stay independent of React, UI, and transport, including type-only dependencies.
|
||||
- Production Canvas callers use `canvas-engine/api.ts`. Keep contracts with the owner of their invariants. Consult the ownership manifest before adding Workbench modules.
|
||||
- Keep wire DTOs and persisted schemas behind explicit mappings/serializers. Do not grow compatibility re-exports into implementations or add architecture exceptions to make a check pass.
|
||||
- TanStack Query owns backend read models; non-React runtimes own orchestration and lifecycle policy. Use stable, narrowly selected external-store snapshots instead of mirroring broad stores in component state.
|
||||
- Preserve account/project isolation, stale-result fencing, revision conflicts, reconnect behavior, and start/dispose ownership. No process-wide mutable caches for per-account/project lifetimes.
|
||||
- Read `src/workbench/projects/README.md` for persistence changes: backend authority, bounded recovery storage, cross-tab ownership, durable queue receipts, and explicit conflict decisions are behavioral contracts.
|
||||
|
||||
## React and product quality
|
||||
|
||||
- Add no direct `useEffect` calls. Derive values during render, handle actions in event handlers, fetch through Query, and subscribe through external-store adapters.
|
||||
- Use the existing `@platform/react/useMountEffect` only for genuine mount/unmount registration with stable dependencies and complete cleanup. Do not hide changing dependencies in refs, introduce wrapper aliases, or use layout effects to evade this rule. Layout effects are reserved for required pre-paint DOM measurement.
|
||||
- Migrate an existing effect when changing its behavior; do not sweep unrelated effects. When an identity changes, use the appropriate store/runtime lifecycle or deliberate keyed remount without losing user state accidentally.
|
||||
- Reuse Platform UI controls, Chakra/theme tokens, icons, and established interaction patterns. Do not introduce a second styling system or adopt Next.js/SWR examples from generic skills.
|
||||
- Finish loading, empty, error, disabled, and recovery states. Keep keyboard operation, visible focus, focus restoration, accessible names, and alternatives to pointer-only interactions intact.
|
||||
- Maintain a dense, usable desktop layout across window sizes and zoom levels. Check overflow, long/localized text, selected/hover/active states, and theme consistency. Use existing localization conventions.
|
||||
- Keep frequent interactions immediate and motion restrained, interruptible, and compatible with reduced-motion preferences. Specify transition properties; avoid animation that delays editing or is the only state cue.
|
||||
- Inspect changed flows in a browser and provide relevant visual evidence. Browser tests and axe checks complement visual/interaction review rather than replacing it.
|
||||
|
||||
## Performance and validation
|
||||
|
||||
- Inspect affected render/subscription paths, large galleries/lists, pointer handlers, Canvas resources, lazy module loading, and request scheduling for related efficiency wins. Use existing virtualization and lazy boundaries; do not add memoization without an identified cost.
|
||||
- Preserve resource disposal, bounded memory, account transitions, and responsive input. Measure material performance claims with the existing budgets and representative fixtures. Do not casually update goldens or baselines to hide regressions.
|
||||
- Commands below run from this directory (or use `pnpm -C invokeai/frontend/webv2`). Install using `pnpm install --frozen-lockfile` with the existing lockfile.
|
||||
|
||||
| Change/check | Command |
|
||||
| ------------------------------------- | ------------------------------------------------------------------ |
|
||||
| Formatting, lint, types, architecture | `pnpm lint` |
|
||||
| Focused behavior | `pnpm test <test-path>` or `pnpm test:browser <browser-test-path>` |
|
||||
| Unit, Chromium, mock-backend fixtures | `pnpm test:all` |
|
||||
| Architecture and browser performance | `pnpm test:performance:architecture` |
|
||||
| Project-file integration | `pnpm test:project-files` |
|
||||
| Accessibility in a fresh build | `pnpm test:accessibility` |
|
||||
| Milestone/release completion | `pnpm check:release` |
|
||||
|
||||
Install Chromium with `pnpm exec playwright install chromium` if missing (`--with-deps` in Linux CI). Unit tests are colocated `*.test.ts`/`*.test.tsx`; real-browser tests are `*.browser.test.ts`/`*.browser.test.tsx`. Test real IndexedDB, Web Locks, focus, pointer, and rendering behavior where mocks cannot establish correctness.
|
||||
|
||||
`check:release` includes lint, all tests, architecture performance/build, project-file journeys, and accessibility. Architecture inventories and performance reports go to ignored `artifacts/`; do not commit them. Run focused checks during development, then the completion gate before calling a code milestone ready. Documentation-only changes need formatting/link review, not unrelated application tests.
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -193,6 +193,8 @@ const surfaces = [
|
||||
await waitForWorkbench(page);
|
||||
await selectLayoutPreset(page, 'Compose', 'Preview');
|
||||
await selectCenterView(page, 'Preview', 'Gallery');
|
||||
// The default project board is empty; scan the populated fixture gallery.
|
||||
await centerRegion(page).getByRole('button').filter({ hasText: 'Uncategorized' }).click();
|
||||
await centerRegion(page).getByRole('list', { exact: true, name: 'Gallery items' }).waitFor();
|
||||
},
|
||||
},
|
||||
@@ -600,6 +602,7 @@ const runVideoPreviewJourney = async (browser) => {
|
||||
await selectLayoutPreset(page, 'Compose', 'Preview');
|
||||
|
||||
const rightPanel = page.getByRole('complementary', { exact: true, name: 'right widget panel' });
|
||||
await rightPanel.getByRole('button').filter({ hasText: 'Uncategorized' }).click();
|
||||
const gallery = rightPanel.getByRole('list', { exact: true, name: 'Gallery items' });
|
||||
const selectVideo = rightPanel.getByRole('button', {
|
||||
exact: true,
|
||||
@@ -712,6 +715,7 @@ const runKeepAliveStateJourney = async (browser) => {
|
||||
await selectLayoutPreset(page, 'Compose', 'Preview');
|
||||
|
||||
const rightPanel = page.getByRole('complementary', { exact: true, name: 'right widget panel' });
|
||||
await rightPanel.getByRole('button').filter({ hasText: 'Uncategorized' }).click();
|
||||
const galleryItems = rightPanel.getByRole('list', { exact: true, name: 'Gallery items' });
|
||||
await galleryItems.waitFor();
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Python tests
|
||||
|
||||
- Read guidance for the production code under test. Follow existing suite placement (`tests/app/`, `tests/backend/`, or the owning root suite) and reuse appropriate fixtures from `conftest.py` and `fixtures/`.
|
||||
- Protect observable behavior at the interface that owns it. A test should fail for a plausible regression, use independently derived expectations, and survive implementation refactors that preserve the contract.
|
||||
- Avoid trivial type/constant/re-export tests, snapshots of incidental structure, duplicate coverage, implementation-shaped mock choreography, and benchmarks without a meaningful question. Remove obsolete tests.
|
||||
- Reproduce bugs with a focused failing case when feasible. Add edge/failure cases where they protect real behavior, not every imaginable branch. Use names describing outcomes.
|
||||
- Prefer real temporary SQLite/filesystem/tensor operations when they establish the behavior. Mock external services, expensive models, or unavailable hardware at an appropriate interface; never mock away the transaction, authorization, concurrency, or numerical behavior being checked.
|
||||
- Isolate filesystem paths, databases, account identities, clocks, random seeds, environment changes, and network behavior. Clean up subprocesses, listeners, patches, and resources. Never use production model/database/output directories.
|
||||
- Exercise rollback, revisions, cross-user isolation, retries, cancellation, resource bounds, and cleanup when affected. Frontend IndexedDB, Web Locks, focus, and rendering belong in webv2's real-browser tests.
|
||||
- Run `uv run --no-sync pytest <test-paths>` from the root for focused checks; CI uses `uv run --no-sync pytest`. Configuration excludes `slow` by default. Use `-m slow` for selected slow tests or `-m ""` to include them deliberately.
|
||||
- Hardware tests need explicit prerequisites and honest reporting of skips/unavailable devices. Passing mocked or CPU tests does not establish CUDA/ROCm/MPS/XPU behavior.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
Reference in New Issue
Block a user