create-obsession 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +160 -2
  3. package/bin/README.md +6 -0
  4. package/bin/obsession.exe +0 -0
  5. package/bin/obsession.out +0 -0
  6. package/frontend/README.md +41 -0
  7. package/frontend/project-type.json +8 -0
  8. package/frontend/template/.agent/task-scope.example.json +7 -0
  9. package/frontend/template/.editorconfig +11 -0
  10. package/frontend/template/.env +2 -0
  11. package/frontend/template/.env.example +2 -0
  12. package/frontend/template/.github/dependabot.yml +11 -0
  13. package/frontend/template/.github/workflows/quality.yml +28 -0
  14. package/frontend/template/.gitignore.tpl +28 -0
  15. package/frontend/template/.vscode/extensions.json +3 -0
  16. package/frontend/template/.vscode/settings.json +13 -0
  17. package/frontend/template/.vscode/tasks.json +39 -0
  18. package/frontend/template/AGENTS.md +56 -0
  19. package/frontend/template/CLAUDE.md +18 -0
  20. package/frontend/template/README.md.tpl +57 -0
  21. package/frontend/template/docs/CHAPTER_8_9_10_ENFORCEMENT.md +82 -0
  22. package/frontend/template/docs/FEATURE_BLUEPRINT.md +164 -0
  23. package/frontend/template/docs/FRONTEND_ARCHITECTURE.md +132 -0
  24. package/frontend/template/docs/SECURITY_BASELINE.md +32 -0
  25. package/frontend/template/docs/STATE_OWNERSHIP.md +33 -0
  26. package/frontend/template/docs/TASK_PROTOCOL.md +50 -0
  27. package/frontend/template/docs/TASK_SCOPE.md +35 -0
  28. package/frontend/template/docs/TECHNOLOGY_AND_CONFIG.md +96 -0
  29. package/frontend/template/docs/TESTING_AND_GATES.md +109 -0
  30. package/frontend/template/docs/TESTING_STRATEGY.md +34 -0
  31. package/frontend/template/docs/UI_STATES.md +26 -0
  32. package/frontend/template/docs/reference/front-end-structure-course.html +1606 -0
  33. package/frontend/template/docs/reference/frontend-project-setup-manual.docx +0 -0
  34. package/frontend/template/e2e/smoke.spec.ts +12 -0
  35. package/frontend/template/index.html.tpl +13 -0
  36. package/frontend/template/package.json.tpl +45 -0
  37. package/frontend/template/playwright.config.ts +18 -0
  38. package/frontend/template/scripts/check-architecture.mjs +291 -0
  39. package/frontend/template/scripts/check-architecture.test.mjs +93 -0
  40. package/frontend/template/scripts/task-scope.mjs +70 -0
  41. package/frontend/template/scripts/task-scope.test.mjs +46 -0
  42. package/frontend/template/src/app/NotFoundPage.tsx +5 -0
  43. package/frontend/template/src/app/RootLayout.tsx +15 -0
  44. package/frontend/template/src/app/RouteErrorBoundary.tsx +12 -0
  45. package/frontend/template/src/app/main.tsx +11 -0
  46. package/frontend/template/src/app/providers.tsx +12 -0
  47. package/frontend/template/src/app/router.tsx +14 -0
  48. package/frontend/template/src/app/store.ts +12 -0
  49. package/frontend/template/src/features/counter/index.ts +2 -0
  50. package/frontend/template/src/features/counter/model/counterSlice.test.ts +12 -0
  51. package/frontend/template/src/features/counter/model/counterSlice.ts +16 -0
  52. package/frontend/template/src/features/counter/model/selectors.ts +4 -0
  53. package/frontend/template/src/features/counter/ui/CounterWidget.tsx +16 -0
  54. package/frontend/template/src/features/home/index.ts +1 -0
  55. package/frontend/template/src/features/home/routes.tsx +8 -0
  56. package/frontend/template/src/features/home/ui/HomePage.test.tsx +11 -0
  57. package/frontend/template/src/features/home/ui/HomePage.tsx +13 -0
  58. package/frontend/template/src/shared/api/baseApi.ts +9 -0
  59. package/frontend/template/src/shared/api/index.ts +1 -0
  60. package/frontend/template/src/shared/config/env.ts +3 -0
  61. package/frontend/template/src/shared/config/index.ts +1 -0
  62. package/frontend/template/src/shared/ui/Button.tsx +6 -0
  63. package/frontend/template/src/shared/ui/StatusPanel.test.tsx +25 -0
  64. package/frontend/template/src/shared/ui/StatusPanel.tsx +36 -0
  65. package/frontend/template/src/shared/ui/index.ts +4 -0
  66. package/frontend/template/src/shared/ui/styles.css +27 -0
  67. package/frontend/template/src/vite-env.d.ts +1 -0
  68. package/frontend/template/tests/setup.ts +1 -0
  69. package/frontend/template/tsconfig.json +21 -0
  70. package/frontend/template/vite.config.ts +73 -0
  71. package/npm/cli.js +53 -0
  72. package/package.json +30 -4
@@ -0,0 +1,34 @@
1
+ # OBSESSION testing strategy
2
+
3
+ ## What each layer proves
4
+
5
+ - **Static rules / type check**: paths, import graph, TypeScript, format and lint via `vp check` and `scripts/check-architecture.mjs`.
6
+ - **Unit and component tests**: use Vitest and React Testing Library. Verify observable UI behavior and interactions rather than internals or snapshot-only output. Files are colocated (`Button.tsx` / `Button.test.tsx`).
7
+ - **Browser E2E**: use Playwright for navigation, keyboard input, auth flows, error states and real browser integration. Files in `e2e/`, not inside feature source.
8
+ - **Scope**: `task-scope.mjs` checks the exact files the agent changed, separate from test correctness.
9
+ - **Security**: `npm audit` plus weekly Dependabot review.
10
+
11
+ ## Commands
12
+ ```sh
13
+ npm install
14
+ npm run guard
15
+ npm run guard:test
16
+ npm run scope:test
17
+ npm exec -- vp check
18
+ npm exec -- vp test
19
+ npm exec -- vp build
20
+ npm run security:audit
21
+ npx playwright install chromium
22
+ npm run test:e2e
23
+ npm run verify:task # requires task scope started before edits
24
+ ```
25
+
26
+ `npm run verify` intentionally does not install browser binaries or run Playwright; the GitHub Actions `browser-e2e` job installs Chromium and runs E2E. The C wizard offers an optional browser installation/test step to avoid forcing a large browser download.
27
+
28
+ ## Minimum test expectations per new feature
29
+ - One happy path, one failure path and relevant keyboard interaction.
30
+ - Async UI: loading, empty, error and retry; unauthorized and missing resources where applicable.
31
+ - Public API exports and route lazy loading respect the architecture.
32
+ - A Playwright test for each major user-facing journey, not one test for every implementation detail.
33
+ - Avoid brittle selectors: prefer roles, accessible names and Playwright `getByRole`.
34
+ - Never use a passing unit test as evidence that a browser integration works.
@@ -0,0 +1,26 @@
1
+ # Mandatory five-state UX contract
2
+
3
+ Every data-driven feature should decide which of the five states applies. Do not invent success, silently hide errors, or render blank pages.
4
+
5
+ | State | Trigger | Expected user experience | Test |
6
+ |---|---|---|---|
7
+ | Loading | initial data unavailable and request active | status message / skeleton with accessible label; do not announce empty | RTL test for loading indicator |
8
+ | Empty | successful response with zero matching items | explain no results; reset filters / action when relevant | mock successful empty query |
9
+ | Error | request failed (timeout/offline/server error) | clear message and optional retry; don't expose stack/response internals | mock failed request and retry |
10
+ | Unauthorized | unauthenticated (401) or forbidden (403) | safe access message; redirect to sign-in only via approved auth flow | route/auth test |
11
+ | Not-found | unknown route or missing entity (404) | accessible not-found message and safe navigation | Playwright unknown route test |
12
+
13
+ The `src/shared/ui/StatusPanel.tsx` component is a neutral presentational primitive: it takes props and knows nothing about learners, courses, Redux or APIs. Feature code supplies the status based on RTK Query and route data.
14
+
15
+ ## Distinguish stale and initial data
16
+ - `isLoading` with no data: show Loading.
17
+ - Background refresh with cached data (`isFetching`): keep old data visible with a non-blocking indicator.
18
+ - Successful `data=[]`: show Empty, not Error.
19
+ - Network failure after previous data: decide whether to keep stale results with a clear warning and refresh option.
20
+ - 401 and 403 must not be treated as a generic 500. The backend remains responsible for authorization.
21
+
22
+ ## Route-wide boundaries
23
+ `app/RouteErrorBoundary.tsx` handles unexpected router failures without storing business logic. `app/NotFoundPage.tsx` is a catch-all route for missing URLs. Domain-specific missing entities belong inside their owning feature.
24
+
25
+ ## Accessibility
26
+ Use appropriate `role="status"` / `role="alert"`, sensible headings, visible retry controls, keyboard interaction and `aria-busy` for initial loading. Avoid auto-focusing controls or flashing updates without reason.