diff --git a/.claude/launch.json b/.claude/launch.json new file mode 100644 index 00000000..7e45b858 --- /dev/null +++ b/.claude/launch.json @@ -0,0 +1,39 @@ +{ + "version": "0.0.1", + "configurations": [ + { + "name": "vue-demo", + "runtimeExecutable": "npm", + "runtimeArgs": ["--prefix", "vue", "run", "dev"], + "port": 5173 + }, + { + "name": "vue-storybook", + "runtimeExecutable": "npm", + "runtimeArgs": ["--prefix", "vue", "run", "storybook"], + "port": 6006 + }, + { + "name": "django-demo", + "runtimeExecutable": "django/.venv/bin/python", + "runtimeArgs": ["django/manage.py", "runserver"], + "port": 8000 + }, + { + "name": "bff-flask", + "runtimeExecutable": "uv", + "runtimeArgs": [ + "run", + "--project", + "bff", + "flask", + "--app", + "bff/bff.py", + "run", + "--port", + "5022" + ], + "port": 5022 + } + ] +} diff --git a/.gitignore b/.gitignore index 83e11e05..be82a4e4 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ django/docs/source/api/* django/docs/output/**/* .env +*/__pycache__ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 583404ce..ba615afb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,56 +1,62 @@ -# N-SIDE WeFa – Agent Guide +# N-SIDE WeFa - Agent Guide -## Project Snapshot -- WeFa (Web Factory) ships two publishable packages: `django/` contains the `nside-wefa` Django toolkit, `vue/` contains the `@nside/wefa` Vue 3 component library. -- Goal: provide production-ready auth, legal-consent, other backend packages, and UI building blocks so product teams can assemble full-stack experiences quickly. -- Primary technologies: Python 3.12+, Django 5.2 + Django REST Framework, Vitest + Playwright, Vue 3 + PrimeVue + Tailwind 4. +## Purpose -## Repository Layout & Key Docs -- `README.md` – top-level overview; defer to `django/README.md` and `vue/README.md` for workspace specifics. -- `django/` – reusable apps (`nside_wefa.common`, `.authentication`, `.legal_consent`, etc) plus `demo/` project and pytest setup. -- `vue/` – component library, demo playground, Storybook, scripts (e.g. `wefa-install`), and AI guidance (`scripts/files/copilot-instructions.md`). -- Contribution guides: `django/CONTRIBUTE.md` & `vue/CONTRIBUTE.md` define environment setup, quality gates, and release discipline. +This file gives Codex durable repository context. Keep it concise: put shared rules here, put workspace-specific rules in nested `AGENTS.md` files, and move repeatable task workflows into skills. + +Codex loads AGENTS instructions from the repository root down to the current working directory. Later files are more specific, so prefer plain nested `AGENTS.md` files for additive guidance. Use `AGENTS.override.md` only when intentionally replacing broader guidance. + +## Repository Map + +- `django/` publishes the `nside-wefa` Django toolkit with reusable apps under `nside_wefa/` and the `demo/` validation project. +- `vue/` publishes the `@nside/wefa` Vue 3 library, demo app, Storybook docs, CLI helpers, and generated OpenAPI demo clients. +- `bff/` provides the Flask backend-for-frontend for OAuth login/logout/session checks and proxying backend REST calls. +- `scripts/` contains repository automation, especially the version orchestrator used to keep package versions aligned. +- `.github/workflows/` is the source of truth for CI-equivalent validation commands. + +## Technology Baseline + +- Python workspaces target Python 3.12+ and use `uv`, pytest, Ruff, mypy, and security checks. +- `django/` targets modern Django, Django REST Framework, Simple JWT, drf-spectacular, and Hatchling packaging. +- `bff/` uses Flask, Authlib, encrypted token cookies, Docker, and generated OpenAPI documentation. +- `vue/` uses Vue 3, Vite, TypeScript, PrimeVue, Tailwind 4, Pinia, Vue I18n, TanStack Query, Vitest, Storybook, and Playwright. ## Instruction Routing -- For frontend work inside `vue/` (components, containers, stories/docs, translations, tests), use the `$wefa-vue-frontend` skill defined at `skills/wefa-vue-frontend/SKILL.md`. -- For work inside `django/`, use the backend guidance in this file until a dedicated `django/AGENTS.md` is introduced. -- For cross-cutting work (API + UI), follow this file for shared expectations and apply the `wefa-vue-frontend` skill for the frontend part. - -## Core Engineering Principles -- **Convention over configuration**: align with provided settings helpers (`NSIDE_WEFA` for Django and documented Vue defaults) before introducing bespoke wiring. -- **Type safety & documentation**: keep Python and TypeScript hints accurate; add comments only for non-obvious logic; update relevant docs whenever behaviour changes. -- **Tests as gatekeepers**: extend existing suites when behaviour changes; no feature lands without matching tests unless explicitly justified. - -## Backend Playbook (`django/`) -- **App structure**: extend existing apps (`nside_wefa.authentication`, `.legal_consent`, `.common`, etc) unless a new domain warrants a standalone package. Mirror current layout: `apps.py`, `checks.py`, `models/`, `serializers.py`, `urls.py`, `views/`, `tests/`, `README.md`. -- **Settings contract**: all configuration flows through the `NSIDE_WEFA` dict. When adding options, document in `django/README.md`, add system checks in `checks.py`, and ensure defaults keep migrations optional. -- **APIs & serializers**: follow DRF patterns already present; keep authentication utilities DRY by placing shared logic under `utils/`. Expose URLs through `include('nside_wefa..urls')` and cover them in tests. -- **Testing & quality**: use pytest with Django (`pytest` or `python manage.py test`) plus coverage when needed. Run `ruff format .`, `ruff check .`, and `mypy nside_wefa/` before submission. Demo project (`django/demo`) is available for manual validation. - -## Shared Workflow Expectations -- Stay within the workspace toolchain: `uv`/pip + Hatchling builds for Django, npm scripts + Vite for Vue. -- Keep lockfiles consistent with the package manager in use (`uv.lock`, `package-lock.json`). -- Maintain documentation parity: adjust relevant READMEs, MDX docs, or changelog entries (once introduced) whenever behaviour changes. -- For cross-cutting features, coordinate backend API shape first, then wire the frontend through the generated clients/composables. - -## Decision Checklists -- **Before shipping backend change**: - - [ ] Update/extend system checks and settings docs. - - [ ] Provide migrations only when required and reversible. - - [ ] Add pytest coverage for new branches/edge cases. -- **Before opening a PR**: - - [ ] Run required backend lint/format/test commands. - - [ ] Update backend docs/demo snippets as needed. - - [ ] Document breaking changes and version impacts. - -## Quick Command Reference -- Backend install: `cd django && pip install -e .[dev]` (or `uv sync --all-extras`) -- Backend tests: `cd django && pytest` -- Backend lint/type: `cd django && ruff check . && ruff format --check && mypy nside_wefa/` - -## When in Doubt -- Re-read the relevant `README.md` and `CONTRIBUTE.md` before altering flows. -- Trace existing backend implementations (e.g., `nside_wefa/legal_consent`) to mirror patterns. -- Surface open questions early (e.g., new authentication modes) so design/system owners can confirm direction. - -Following this guide keeps contributions aligned with the existing architecture, ensures compliance with the WeFa component hierarchy, and preserves release quality across both Django and Vue packages. + +- For `django/` work, read `django/AGENTS.md`, `django/README.md`, and `django/CONTRIBUTE.md`. +- For `vue/` work, read `vue/AGENTS.md`, `vue/README.md`, and `vue/CONTRIBUTE.md`; use `$wefa-vue-frontend` for component, container, Storybook, i18n, demo, and frontend test work. +- For TanStack Query work in `vue/`, also use `$wefa-tanstack-query`. +- For `bff/` work, read `bff/AGENTS.md` and `bff/README.md`. +- For `scripts/` work, read `scripts/AGENTS.md`. +- For cross-cutting changes, coordinate backend/API shape first, then update consumers and documentation in the affected workspaces. + +The current repository skills live under `skills/`. A later cleanup should migrate shared Codex skills to official repository discovery under `.agents/skills`, but do not do that as part of AGENTS-only edits unless explicitly requested. + +## Shared Engineering Rules + +- Explore first: inspect existing implementations, neighboring files, docs, and CI before designing changes. +- Prefer existing conventions and helpers over new bespoke wiring. +- Preserve public APIs unless the task explicitly asks for a breaking change; document behavior changes where consumers will notice them. +- Keep Python and TypeScript types accurate. Avoid broad casts, silent fallbacks, and broad exception handling. +- Keep user-facing copy localized in frontend code and documented in the relevant README, MDX, or package docs. +- Add or update tests when behavior changes. If validation is skipped, state exactly why. +- Do not hand-edit generated artifacts unless the workspace guide explicitly allows it. +- Do not commit secrets. Treat `.env` files, OAuth credentials, tokens, and generated local IDE/cache files as local-only. + +## Versioning And Releases + +- The monorepo uses one shared version across `django/`, `vue/`, and `bff/`. +- Use `python3 scripts/wefa_version.py` from the repository root for version changes. +- Prefer `--dry-run` before version changes; do not manually edit per-package version fields unless repairing the orchestrator itself. +- Keep lockfiles consistent with the package manager used in the branch: `uv.lock` for Python workspaces and `package-lock.json` for npm. + +## Validation Expectations + +- Run the smallest relevant checks while iterating, then run the workspace's CI-equivalent commands before handoff when feasible. +- Documentation-only AGENTS changes do not require product test suites, but they should pass basic markdown/content sanity checks. +- For reviews, prioritize bugs, behavior regressions, missing tests, security risks, and docs drift before style suggestions. + +## Compatibility Notes + +- Codex guidance should come from `AGENTS.md` files and skills, not generated assistant instruction artifacts. +- Keep AGENTS files compact. Link to workspace docs rather than copying full manuals so the combined instruction chain stays below Codex's default 32 KiB project-doc size limit. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bff/AGENTS.md b/bff/AGENTS.md new file mode 100644 index 00000000..eecd56d6 --- /dev/null +++ b/bff/AGENTS.md @@ -0,0 +1,48 @@ +# WeFa BFF - Agent Guide + +## Scope + +This file applies to the Flask backend-for-frontend in `bff/`. The service handles OAuth login/logout/session checks, encrypted token cookies, health endpoints, OpenAPI generation, and proxying backend REST calls. + +Read `bff/README.md` before changing environment contracts, auth/session behavior, OpenAPI output, Docker behavior, or deployment-facing docs. + +## Security And Configuration Rules + +- Never commit `.env`, OAuth credentials, token values, cookie encryption keys, or local IDE/cache artifacts. +- Keep `.env.example` and README documentation in sync with required and optional settings. +- Required settings should fail fast at startup when missing or blank. +- Preserve production security defaults unless explicitly directed otherwise: HttpOnly token cookies, secure cookie settings, strict SameSite behavior, PKCE verifier/state handling, and explicit callback error handling. +- Token cookies are derived from `SESSION_COOKIE_NAME`; changes to names, payload split behavior, encryption, or expiry semantics need tests and rollout notes. +- Do not add broad proxy fallbacks that hide backend failures. Surface upstream errors consistently with existing route behavior. + +## Implementation Rules + +- Keep route handlers in `bff_app/routes/` and reusable behavior in `bff_app/services/` or `bff_app/settings.py`. +- Preserve the OpenAPI generator as the source of truth for `bff_app/openapi/openapi.yaml`. +- Use `uv` for dependency and command execution in this workspace. +- Update Docker and README instructions together when runtime ports, environment variables, or startup commands change. + +## Tests And OpenAPI + +- Add or update tests under `tests/` for auth redirects, callback errors, session behavior, token-cookie behavior, proxying, settings validation, and OpenAPI generation. +- Regenerate OpenAPI intentionally, then check for drift. +- Use narrow pytest runs while iterating, then the CI-equivalent checks before handoff when feasible. + +## Validation Commands + +Run from `bff/` unless noted: + +```bash +uv run pytest -q +uv run python -m bff_app.openapi.generate --check --output bff_app/openapi/openapi.yaml +uvx pysentry-rs --config .pysentry.toml . +``` + +For manual local validation: + +```bash +FLASK_RUN_PORT=5022 uv run flask --app bff.py run +docker-compose up --build +``` + +Only run server or Docker commands when manual behavior verification is needed. diff --git a/bff/CLAUDE.md b/bff/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/bff/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/django/AGENTS.md b/django/AGENTS.md new file mode 100644 index 00000000..23f53279 --- /dev/null +++ b/django/AGENTS.md @@ -0,0 +1,48 @@ +# WeFa Django - Agent Guide + +## Scope + +This file applies to the Django toolkit in `django/`. The package publishes `nside-wefa` and contains reusable apps under `nside_wefa/` plus the `demo/` project used for local and CI validation. + +Read `django/README.md` and `django/CONTRIBUTE.md` before changing public behavior, settings, migrations, or release-facing docs. + +## Architecture Rules + +- Extend existing apps when the domain fits: `common`, `authentication`, `legal_consent`, `locale`, `audit`, `attachments`, `admin_theme`, or `utils`. +- Mirror the existing app layout: `apps.py`, `checks.py`, `models/`, `serializers.py`, `urls.py`, `views/`, `tests/`, and app-level README files where applicable. +- Keep all project configuration under the `NSIDE_WEFA` settings dictionary. New settings need defaults, Django system checks, tests, and README documentation. +- `nside_wefa.common` is foundational and should remain before dependent WeFa apps in `INSTALLED_APPS` examples. +- Prefer Django and DRF conventions over custom framework code. Put shared authentication or request helpers under the nearest `utils/` module. +- Expose app routes through `include("nside_wefa..urls")` and cover URL/API behavior in tests. + +## Data, Migrations, And Checks + +- Add migrations only when model state changes. Keep them reversible unless Django cannot reasonably reverse the operation. +- Run `python manage.py makemigrations --check --dry-run` when model or field definitions change. +- Run `python manage.py check` or targeted system-check tests when changing settings contracts. +- Preserve existing data semantics for legal consent, audit events, locale preferences, and authentication unless the task explicitly defines a migration path. +- Audit-related changes must preserve append-only expectations and document any tamper-evident or retention behavior changes. + +## Documentation And Tests + +- Update `django/README.md`, app READMEs, or demo snippets when configuration, URLs, APIs, or behavior changes. +- Add pytest coverage for new branches, validation checks, serializers, views, management commands, and migrations where relevant. +- Use the demo project for manual verification when behavior depends on Django settings or installed app ordering. + +## Validation Commands + +Run from `django/` unless noted: + +```bash +uv run ruff check . +uv run ruff format --check . +DJANGO_SETTINGS_MODULE=demo.settings uv run mypy --install-types --non-interactive . +python manage.py makemigrations --check --dry-run +python manage.py migrate --plan +python manage.py migrate --noinput +uv run pytest --cov-config=.coveragerc --cov-report xml --cov . +uvx pysentry-rs --config .pysentry.toml . +uv run bandit -c pyproject.toml -r nside_wefa -n 3 -l +``` + +If running a smaller subset, choose the narrowest command that exercises the changed app and state what remains unrun. diff --git a/django/CLAUDE.md b/django/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/django/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 00000000..14b14d0f --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,35 @@ +# WeFa Scripts - Agent Guide + +## Scope + +This file applies to repository automation under `scripts/`, including the shared version orchestrator. + +Read the root `README.md` release/versioning section before changing version automation or release-facing behavior. + +## Versioning Rules + +- The monorepo uses one shared version across `django/`, `vue/`, and `bff/`. +- `scripts/wefa_version.py` is the owner for version reads, checks, bumps, and explicit sets. +- Do not manually edit per-package version fields in `django/pyproject.toml`, `vue/package.json`, `vue/package-lock.json`, or `bff/pyproject.toml` unless the task is to repair the orchestrator or generated version state. +- Prefer `python3 scripts/wefa_version.py --dry-run` before commands that mutate version files. +- Preserve SemVer input rules and PEP 440 normalization for Python project files. +- Keep prerelease support limited to the identifiers documented in the root README unless the release policy changes. + +## Implementation Rules + +- Keep automation deterministic, non-interactive by default, and safe to run from CI. +- Use explicit errors for inconsistent version state instead of silently normalizing unexpected values. +- Update root README release/versioning docs when command behavior or supported version formats change. +- Avoid adding dependencies for simple automation; if a dependency is necessary, document why. + +## Validation Commands + +Run from the repository root: + +```bash +python3 -m unittest discover -s scripts -p 'test_*.py' +python3 scripts/wefa_version.py show +python3 scripts/wefa_version.py check --expect "$(python3 scripts/wefa_version.py show)" +``` + +For mutating version command changes, also run representative `--dry-run` bump and set commands before any real mutation. diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/scripts/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/vue/.github/copilot-instructions.md b/vue/.github/copilot-instructions.md deleted file mode 100644 index 7fca9627..00000000 --- a/vue/.github/copilot-instructions.md +++ /dev/null @@ -1,270 +0,0 @@ -# N-SIDE WeFa- Development Instructions - -## Project Overview -**This is a PrimeVue-based component library superset** (`@nside/wefa`) built with Vue 3 and TypeScript. The library extends and enhances PrimeVue components with additional functionality, custom styling using Tailwind CSS, and domain-specific features for energy management applications. - -### Core Architecture -- **Base Framework**: PrimeVue 4.3.6 as the foundational UI component library -- **Enhancement Layer**: Custom components that wrap, extend, or compose PrimeVue components -- **Styling**: Tailwind CSS 4.1.11 with PrimeUI integration - **NO custom CSS files** -- **Component Pattern**: Each component is a superset that adds value to existing PrimeVue functionality - -## Component Development Guidelines - -### Required Deliverables for Each Component -Every component exposed by this library **MUST** include: - -1. **Single File Component (SFC)**: The main `.vue` component file -2. **Storybook Stories**: `.stories.ts` file with interaction tests. Never includes the `autodocs` tag. -3. **Unit Tests**: `.spec.ts` file with comprehensive test coverage -4. **MDX Documentation**: `.mdx` file with complete documentation including use cases. - -### Component Development Pattern -When creating new components, follow this established pattern: - -#### 1. Use PrimeVue as Foundation -```typescript -// Import PrimeVue components when needed -import Breadcrumb from 'primevue/breadcrumb' -import type { MenuItem } from 'primevue/menuitem' - -// Extend or compose PrimeVue functionality -export interface YourComponentProps { - // Add your custom props that enhance PrimeVue behavior -} -``` - -#### 2. Style with Tailwind Only -- **DO**: Use Tailwind CSS classes for all styling -- **DO**: Leverage `tailwindcss-primeui` for PrimeVue component styling -- **DON'T**: Create custom CSS files or ` - - -import './custom-styles.css' -``` - -**✅ REQUIRED APPROACH:** - -```vue - -
- -``` - -**📚 STYLING RESOURCES:** -- **Tailwind Classes**: https://tailwindcss.com/docs -- **PrimeVue Integration**: Use `tailwindcss-primeui` package -- **Theme System**: Leverage `@primeuix/themes` integration - ---- - -## 📋 AI AGENT IMPLEMENTATION EXAMPLES - -### ❌ VIOLATION EXAMPLE (AUTO-REJECT) - -```vue - - - -``` - -### ✅ CORRECT IMPLEMENTATION PATTERNS - -#### Pattern 1: WeFa First Choice -```vue - - - -``` - -#### Pattern 2: PrimeVue Composition (When WeFa Unavailable) -```vue - - - -``` - -#### Pattern 3: Complex Form Composition -```vue - - - -``` - -## Component Usage Guidelines - -### WeFa Components -```vue - -``` - -### PrimeVue Components (when WeFa doesn't have equivalent) -```vue - -``` - -### Common Tailwind Patterns for PrimeVue -```vue - -``` - ---- - -## 🔄 AI AGENT DECISION FLOW ALGORITHM - -### 🎯 STEP-BY-STEP COMPONENT SELECTION - -```mermaid -flowchart TD - A[Need UI Component] --> B{WeFa has component?} - B -->|YES| C[✅ Use WeFa
Import from @nside/wefa
END] - B -->|NO| D{Can compose with PrimeVue?} - D -->|YES| E[✅ Use PrimeVue Composition
+ Tailwind Classes
END] - D -->|NO| F[⚠️ Native HTML
+ Justification Comment
END] -``` - -### 📋 MANDATORY VALIDATION CHECKLIST - -**🔍 PRE-IMPLEMENTATION VALIDATION:** -Before writing any component code, AI agents MUST verify: - -``` -[ ] 1. COMPONENT CHECK: Searched @nside/wefa exports -[ ] 2. COMPOSITION CHECK: Evaluated PrimeVue component combination -[ ] 3. STYLING CHECK: Planned Tailwind-only approach -[ ] 4. FALLBACK CHECK: Prepared justification if using HTML -``` - -**✅ POST-IMPLEMENTATION VALIDATION:** -After writing component code, AI agents MUST validate: - -``` -[ ] ✅ IMPORT: WeFa components from '@nside/wefa' -[ ] ✅ IMPORT: PrimeVue components from 'primevue/[component]' -[ ] ✅ STYLING: Only Tailwind CSS classes used -[ ] ✅ FORBIDDEN: No