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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HassanElAmrani
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,161 @@
1
- # Temporary Holding Version
1
+ # OBSESSION
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Retro terminal project initializer — GitHub-ready source repository.**
4
+
5
+ OBSESSION scaffolds projects from **project-type folders**. The only supported type at present is `frontend/`. Adding other types later should not change the generated frontend architecture.
6
+
7
+ ```text
8
+ OBSESSION/
9
+ ├── frontend/ # PROJECT TYPE 01: FRONTEND
10
+ │ ├── template/ # Files copied into each new React project
11
+ │ │ ├── src/app/ # Composition, routes and providers
12
+ │ │ ├── src/features/ # Flat, small business features
13
+ │ │ ├── src/shared/ # Business-neutral tools
14
+ │ │ ├── scripts/ # Architecture and task-scope guards
15
+ │ │ ├── docs/ # Architecture, agent workflow, states, security
16
+ │ │ ├── e2e/ # Playwright browser tests
17
+ │ │ ├── tests/ # React Testing Library setup
18
+ │ │ ├── .agent/ # Task scope example
19
+ │ │ ├── .github/ # App CI and Dependabot rules
20
+ │ │ ├── .vscode/ # Editor tasks and settings
21
+ │ │ ├── .env.example # Public frontend config example
22
+ │ │ ├── .gitignore.tpl # Becomes .gitignore (.tpl survives npm publish)
23
+ │ │ ├── CLAUDE.md / AGENTS.md
24
+ │ │ └── vite.config.ts, package.json.tpl, ...
25
+ │ ├── project-type.json # Type catalogue metadata (informational)
26
+ │ └── README.md
27
+ ├── core/init_OBSESSION.c # Native C CLI: menu, copy, run npm/Vite+
28
+ ├── bin/obsession.out # Prebuilt Linux x86_64 executable
29
+ ├── scripts/ # Reproducible Linux and Windows builds + smoke tests
30
+ ├── docs/ # Setup, GitHub releases and operating workflow
31
+ ├── .github/workflows/ # Build and test both OS binaries on GitHub
32
+ ├── .editorconfig
33
+ ├── .gitignore
34
+ └── README.md
35
+ ```
36
+
37
+ ## Quick start with npm (Windows x64 and Linux x64)
38
+
39
+ ```bash
40
+ npm create obsession@latest my-app
41
+ ```
42
+
43
+ Other ways to run it:
44
+
45
+ ```bash
46
+ npx create-obsession my-app # same thing
47
+ npm create obsession@latest # interactive wizard
48
+ npm create obsession@latest my-app -- --no-install --no-git
49
+ npm install -g create-obsession # then: obsession my-app
50
+ ```
51
+
52
+ The npm package `create-obsession` contains the native C binaries and `frontend/template/`. `npm/cli.js` picks the binary for your platform and forwards all options. A first argument without `--` is treated as `--name`. Options after `npm create obsession@latest my-app` need a `--` separator.
53
+
54
+ Publishing is automated: pushing a tag `vX.Y.Z` that matches `package.json` `version` publishes the package (see `docs/GITHUB_AND_RELEASES.md`).
55
+
56
+ ## Start on Linux x86_64
57
+
58
+ From the extracted OBSESSION repository:
59
+
60
+ ```bash
61
+ ./bin/obsession.out
62
+ ```
63
+
64
+ If the prebuilt binary is incompatible with your Linux distribution, rebuild from C:
65
+
66
+ ```bash
67
+ sh scripts/build-linux.sh
68
+ ./bin/obsession.out
69
+ ```
70
+
71
+ ## Start on Windows (VS Code, PowerShell)
72
+
73
+ Get `obsession.exe` from the **GitHub Actions Windows artifact or release bundle** or build locally with a Windows C compiler:
74
+
75
+ ```powershell
76
+ .\scripts\build-windows.bat
77
+ .\bin\obsession.exe
78
+ ```
79
+
80
+ The ZIP includes the **Linux binary**. A compiled Windows binary is not included in this source ZIP because a Windows C cross-compiler is unavailable in the package-generation environment. The repository has a Windows build workflow: **Actions → Build OBSESSION → Windows artifact**. The Windows build runs automatically on pushes and on tagged releases. A real Windows `.exe` is generated there, not a renamed Linux file.
81
+
82
+ **Keep the `bin/` and `frontend/` folders in the same extracted repository.** The executable loads `../frontend/template/` relative to its location.
83
+
84
+ ## Create a frontend project (interactive)
85
+
86
+ The wizard shows an animated retro **OBSESSION** banner and asks for:
87
+
88
+ 1. Project type: **Frontend** (only current choice)
89
+ 2. Project name and existing destination parent directory
90
+ 3. Git initialization
91
+ 4. Dependency installation and validation
92
+ 5. Optional Playwright Chromium browser download and E2E run
93
+ 6. Final confirmation before writing files
94
+
95
+ ## Create a frontend project (non-interactive / safe offline mode)
96
+
97
+ Linux:
98
+
99
+ ```bash
100
+ ./bin/obsession.out --type frontend --name learning-portal --parent . --no-install --no-git --no-animation
101
+ ```
102
+
103
+ Windows:
104
+
105
+ ```powershell
106
+ .\bin\obsession.exe --type frontend --name learning-portal --parent . --no-install --no-git --no-animation
107
+ ```
108
+
109
+ **Safety:** the target must not exist. OBSESSION refuses overwrites. It validates npm-style project names, copies only bundled template files, and uses separate process arguments for the Linux CLI instead of shell-building user input. Dependencies are installed only with your selected option.
110
+
111
+ ## The generated frontend stack
112
+
113
+ - React + TypeScript, React Router, Redux Toolkit, RTK Query, Vite+
114
+ - Three zones: `app/` (composition) → `features/` (business capabilities) → `shared/` (generic primitives)
115
+ - Small, flat feature folders; public feature `index.ts` and one-direction dependencies
116
+ - Rules for choosing `useState`, URL search parameters, Redux and RTK Query
117
+ - UI states: loading, empty, error, unauthorized and not-found
118
+ - Oxlint and independent import-graph checks; task-scope manifest validation
119
+ - React Testing Library, Vitest, Playwright Chromium tests
120
+ - npm audit and Dependabot updates; GitHub Actions CI
121
+ - `.env`, `.env.example`, `.gitignore`, `.editorconfig`, `CLAUDE.md`, `AGENTS.md`, `.vscode/`
122
+
123
+ Run this *inside the generated application* after installing dependencies:
124
+
125
+ ```bash
126
+ npm install
127
+ npm run verify
128
+ npx playwright install chromium
129
+ npm run test:e2e
130
+ npm run dev
131
+ ```
132
+
133
+ > Current Vite+ / bundled Vitest requires a supported Node runtime (for example Node 24 LTS). A template generated without `npm install` is not a tested production build. First install generates `package-lock.json`, which should be committed for CI (`npm ci`).
134
+
135
+ ## Quality of the initializer itself
136
+
137
+ ```bash
138
+ sh scripts/build-linux.sh
139
+ sh scripts/test-scaffold.sh
140
+ ```
141
+
142
+ GitHub Actions also builds **Windows x86_64** with MinGW-w64, checks basic CLI/scaffold operations, and publishes binary artifacts. See `docs/GITHUB_AND_RELEASES.md`.
143
+
144
+ ## Responsibilities
145
+
146
+ - **OBSESSION core:** create files, launch package manager/toolchain as child processes, report real results.
147
+ - **Vite+:** build, check, test, run React projects. The C program does not implement Vite or React.
148
+ - **Agent rules:** constrain expected changes; CI and code review enforce merge/release gates.
149
+ - **GitHub repo:** keep this initializer source and project-type templates in version control; every generated project should have its *own* repository.
150
+
151
+ ## Documentation
152
+
153
+ - `docs/GITHUB_AND_RELEASES.md` — upload, artifacts, GitHub workflow and Windows `.exe` production
154
+ - `docs/QUALITY_AND_DEPLOYMENT.md` — agent + Jira + GitHub + Slack + release process
155
+ - `frontend/README.md` — frontend template layout and extension policy
156
+
157
+ **Status:** The included Linux binary and file-only scaffolding can be tested locally. A full npm install, Vite+ build and Playwright browser run need to be executed on your development machine or CI with a compatible Node runtime and network access.
158
+
159
+ ## License
160
+
161
+ MIT, see [LICENSE](LICENSE).
package/bin/README.md ADDED
@@ -0,0 +1,6 @@
1
+ # Binary outputs
2
+
3
+ - `obsession.out` — Linux x86_64 ELF, already compiled in this source ZIP. It is generated by `sh scripts/build-linux.sh`.
4
+ - `obsession.exe` — Windows x86_64 PE, compiled by `scripts/build-windows.bat` (requires native Windows GCC) or **GitHub Actions → Build OBSESSION**. This ZIP does **not** include a Windows binary until compiled on the GitHub runner.
5
+
6
+ Both executable formats require the sibling `../frontend/template/` directory. GitHub Actions artifacts and release bundles include this template; standalone executables require the matching OBSESSION repository layout.
Binary file
Binary file
@@ -0,0 +1,41 @@
1
+ # Frontend (project type 01)
2
+
3
+ `template/` is the **single source of truth** for every frontend project scaffolded by OBSESSION.
4
+
5
+ ## Template contents
6
+
7
+ ```text
8
+ frontend/template/
9
+ ├── .agent/ # Example task scope manifest
10
+ ├── .github/ # CI checks + dependency update rules
11
+ ├── .vscode/ # Recommended VS Code settings/tasks
12
+ ├── docs/ # Architecture, state, testing, security, agent protocol
13
+ │ └── reference/ # Original 10-chapter HTML and setup manual
14
+ ├── e2e/ # Playwright smoke test
15
+ ├── scripts/ # Import-graph and changed-file checks
16
+ ├── src/
17
+ │ ├── app/ # Bootstrap, providers, store, router, error screens
18
+ │ ├── features/ # Small, flat home/counter examples
19
+ │ └── shared/ # UI, API base, config
20
+ ├── tests/ # React Testing Library setup
21
+ ├── .env, .env.example, .gitignore, .editorconfig
22
+ ├── CLAUDE.md, AGENTS.md
23
+ ├── package.json.tpl # {{PROJECT_NAME}} is replaced when copied
24
+ ├── index.html.tpl # {{PROJECT_NAME}} is replaced when copied
25
+ ├── playwright.config.ts
26
+ ├── tsconfig.json
27
+ └── vite.config.ts
28
+ ```
29
+
30
+ ## Edit policy
31
+
32
+ - Maintain **small, flat feature folders**; split large capabilities instead of nesting UI components.
33
+ - No feature imports `app/` or another feature's internals; use each feature's `index.ts`.
34
+ - `shared/` must remain business-neutral.
35
+ - Preserve automated checker test cases when modifying architectural rules.
36
+ - Update the chapter documents and generated tests whenever template conventions change.
37
+ - This folder is not itself an npm project; the copied generated project is.
38
+
39
+ ## Future project types
40
+
41
+ Add a new top-level type folder (for example `backend/`) and update the C CLI's project-type selection and template discovery; do not overload `frontend/` with unrelated stacks. `project-type.json` is human-readable metadata, not currently an automatically loaded registry.
@@ -0,0 +1,8 @@
1
+ {
2
+ "id": "frontend",
3
+ "displayName": "Frontend",
4
+ "status": "available",
5
+ "templatePath": "frontend/template",
6
+ "stack": ["React", "TypeScript", "React Router", "Redux Toolkit", "RTK Query", "Vite+"],
7
+ "notes": "Informational metadata; CLI currently has an explicit frontend type switch."
8
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "taskId": "OB-123",
3
+ "allowedPaths": [
4
+ "src/features/home/**",
5
+ "src/app/router.tsx"
6
+ ]
7
+ }
@@ -0,0 +1,11 @@
1
+ root = true
2
+
3
+ [*]
4
+ charset = utf-8
5
+ end_of_line = lf
6
+ insert_final_newline = true
7
+ indent_style = space
8
+ indent_size = 2
9
+
10
+ [*.md]
11
+ trim_trailing_whitespace = false
@@ -0,0 +1,2 @@
1
+ # Public frontend config only. Do not put secrets in VITE_* variables.
2
+ VITE_API_URL=/api
@@ -0,0 +1,2 @@
1
+ # Copy to .env and customize. VITE_* variables are exposed to browsers.
2
+ VITE_API_URL=/api
@@ -0,0 +1,11 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: npm
4
+ directory: '/'
5
+ schedule:
6
+ interval: weekly
7
+ open-pull-requests-limit: 5
8
+ - package-ecosystem: github-actions
9
+ directory: '/'
10
+ schedule:
11
+ interval: weekly
@@ -0,0 +1,28 @@
1
+ name: Frontend quality and security
2
+ on:
3
+ push:
4
+ pull_request:
5
+ permissions:
6
+ contents: read
7
+ jobs:
8
+ quality:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v4
12
+ - uses: actions/setup-node@v4
13
+ with:
14
+ node-version: '24'
15
+ cache: npm
16
+ - run: npm ci
17
+ - run: npm run verify
18
+ browser-e2e:
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: actions/setup-node@v4
23
+ with:
24
+ node-version: '24'
25
+ cache: npm
26
+ - run: npm ci
27
+ - run: npx playwright install --with-deps chromium
28
+ - run: npm run test:e2e
@@ -0,0 +1,28 @@
1
+ # Packages and generated output
2
+ node_modules/
3
+ dist/
4
+ coverage/
5
+ .vite/
6
+ .vite-plus/
7
+ *.log
8
+
9
+ # Secrets: commit .env.example, never local credentials
10
+ .env
11
+ .env.*
12
+ !.env.example
13
+
14
+ # IDE / OS
15
+ .DS_Store
16
+ Thumbs.db
17
+ .idea/
18
+ .vscode/*
19
+ !.vscode/extensions.json
20
+ !.vscode/settings.json
21
+ !.vscode/tasks.json
22
+
23
+ # Task-local scope (not a permission boundary)
24
+ .agent/task-scope.json
25
+
26
+ # Browser tests
27
+ playwright-report/
28
+ test-results/
@@ -0,0 +1,3 @@
1
+ {
2
+ "recommendations": ["VoidZero.vite-plus-extension-pack"]
3
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "editor.defaultFormatter": "oxc.oxc-vscode",
3
+ "[javascript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
4
+ "[javascriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
5
+ "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
6
+ "[typescriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
7
+ "oxc.disableNestedConfig": true,
8
+ "oxc.fmt.disableNestedConfig": true,
9
+ "editor.formatOnSave": true,
10
+ "editor.formatOnSaveMode": "file",
11
+ "editor.codeActionsOnSave": { "source.fixAll.oxc": "explicit" },
12
+ "npm.scriptRunner": "vp"
13
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "version": "2.0.0",
3
+ "tasks": [
4
+ {
5
+ "label": "OBSESSION: Verify Entire Frontend",
6
+ "type": "shell",
7
+ "command": "npm run verify",
8
+ "group": {
9
+ "kind": "test",
10
+ "isDefault": true
11
+ },
12
+ "problemMatcher": []
13
+ },
14
+ {
15
+ "label": "OBSESSION: Check Architecture Only",
16
+ "type": "shell",
17
+ "command": "npm run guard",
18
+ "problemMatcher": []
19
+ },
20
+ {
21
+ "label": "OBSESSION: Verify Task Scope + Entire Frontend",
22
+ "type": "shell",
23
+ "command": "npm run verify:task",
24
+ "problemMatcher": []
25
+ },
26
+ {
27
+ "label": "OBSESSION: Run Playwright E2E",
28
+ "type": "shell",
29
+ "command": "npm run test:e2e",
30
+ "problemMatcher": []
31
+ },
32
+ {
33
+ "label": "OBSESSION: Dependency Security Audit",
34
+ "type": "shell",
35
+ "command": "npm run security:audit",
36
+ "problemMatcher": []
37
+ }
38
+ ]
39
+ }
@@ -0,0 +1,56 @@
1
+ # OBSESSION Frontend Agent Rules
2
+
3
+ These are mandatory project rules for **every task**, not only feature creation.
4
+ Read this file and the following documents before touching source code:
5
+ - `docs/FRONTEND_ARCHITECTURE.md`
6
+ - `docs/TECHNOLOGY_AND_CONFIG.md`
7
+ - `docs/FEATURE_BLUEPRINT.md`
8
+ - `docs/TESTING_AND_GATES.md`
9
+ - `docs/CHAPTER_8_9_10_ENFORCEMENT.md`
10
+ - `docs/TASK_PROTOCOL.md`
11
+
12
+ ## Architecture invariants (no silent exceptions)
13
+
14
+ 1. `src/app/` composes providers, routes, store and layouts. No business logic.
15
+ 2. `src/features/<name>/` owns business UI, model, API, routes, helpers, types.
16
+ 3. Other modules enter each feature only via `@/features/<name>` and its `index.ts`.
17
+ 4. `src/shared/` is business-neutral; never import from `app/` or `features/`.
18
+ 5. Imports point down; no cycles, including cycles involving `import type`.
19
+ 6. Feature model never imports UI. Shared UI receives data through props.
20
+ 7. Create shared abstractions only after a second real feature needs them and they pass the copy test.
21
+ 8. Each feature owns lazy routes and its own Redux state. Server data belongs in RTK Query endpoints.
22
+ 9. Use `@/` alias to cross zones. Avoid `../../` and other import disguises.
23
+ 10. Do not change architecture, tooling, security assumptions, or dependencies without explicit approval.
24
+
25
+ ## One task, one bounded change
26
+
27
+ Before editing: record goal, acceptance criteria, affected feature, allowed paths, approved app wiring and prohibited paths. Check existing code and relevant tests. Do not broaden scope without asking.
28
+
29
+ During editing: work in one room (`ui`, `model`, `api`, `lib`, `routes`) at a time; add meaningful colocated tests. Do not modify unrelated modules. Never discard unrelated worktree changes.
30
+
31
+ After editing: **run and report**, from the project root:
32
+
33
+ ```bash
34
+ npm run guard
35
+ npm run guard:test
36
+ npm exec -- vp check
37
+ npm exec -- vp test
38
+ npm exec -- vp build
39
+ ```
40
+
41
+ Review `git status --short`, `git diff --stat`, `git diff`, and **untracked** new files. Recheck each Rule A-H in `docs/TESTING_AND_GATES.md` and each acceptance criterion. Report changed files, exact commands/results, exceptions, risks and a final PASS / FAIL / BLOCKED status. Never claim success for skipped or failing gates.
42
+
43
+ The linter and architecture checker implement guardrails but cannot prove code ownership, acceptance criteria, adequate coverage or user experience. These require a manual agent review.
44
+
45
+ ## OBSESSION v1.1 - Non-negotiable task gates
46
+
47
+ - Keep feature rooms flat. Do not create `src/features/x/ui/components/`, deeply nested feature rooms, or monolithic features. Split work into small sibling capability features with explicit `index.ts` doors.
48
+ - Before modifying any project files, obtain agreement on the task scope, then run:
49
+ `npm run scope:start -- --id OB-123 --allow "src/features/example/**"`
50
+ Add each approved wiring/config path as its own `--allow` argument.
51
+ - After the task, run `npm run verify:task` (includes scope check), then review actual diffs. If scope check fails, stop; do not broaden scope unilaterally.
52
+ - Each feature decides where state lives using `docs/STATE_OWNERSHIP.md`.
53
+ - Every asynchronous user-facing page must define loading, empty, error, unauthorized and not-found behavior; consult `docs/UI_STATES.md`.
54
+ - For React UI, write behavioral tests with React Testing Library and appropriate Playwright E2E journeys; consult `docs/TESTING_STRATEGY.md`.
55
+ - Any new dependency or dependency update requires review, `npm audit --audit-level=high` and lockfile changes; follow `docs/SECURITY_BASELINE.md`.
56
+ - A scope manifest is a local change detector, not a security sandbox. Protected branches and human review remain essential.
@@ -0,0 +1,18 @@
1
+ # Claude Code - OBSESSION
2
+
3
+ **Always start by reading `AGENTS.md`** and the referenced architecture, enforcement and task workflow documents. Do not treat a new task, Jira ticket or Slack message as permission to change the architecture.
4
+
5
+ Before editing, explicitly state the task boundary (allowed paths, permitted app wiring, non-goals), and review the working tree. Implement one module/room at a time. After editing, run the actual gates from `AGENTS.md`, review the complete diff including untracked files, and report PASS/FAIL/BLOCKED with evidence. When a gate cannot run, mark the task BLOCKED. Never silently weaken tests, lint rules or boundary checks.
6
+
7
+ ## OBSESSION v1.1 - Non-negotiable task gates
8
+
9
+ - Keep feature rooms flat. Do not create `src/features/x/ui/components/`, deeply nested feature rooms, or monolithic features. Split work into small sibling capability features with explicit `index.ts` doors.
10
+ - Before modifying any project files, obtain agreement on the task scope, then run:
11
+ `npm run scope:start -- --id OB-123 --allow "src/features/example/**"`
12
+ Add each approved wiring/config path as its own `--allow` argument.
13
+ - After the task, run `npm run verify:task` (includes scope check), then review actual diffs. If scope check fails, stop; do not broaden scope unilaterally.
14
+ - Each feature decides where state lives using `docs/STATE_OWNERSHIP.md`.
15
+ - Every asynchronous user-facing page must define loading, empty, error, unauthorized and not-found behavior; consult `docs/UI_STATES.md`.
16
+ - For React UI, write behavioral tests with React Testing Library and appropriate Playwright E2E journeys; consult `docs/TESTING_STRATEGY.md`.
17
+ - Any new dependency or dependency update requires review, `npm audit --audit-level=high` and lockfile changes; follow `docs/SECURITY_BASELINE.md`.
18
+ - A scope manifest is a local change detector, not a security sandbox. Protected branches and human review remain essential.
@@ -0,0 +1,57 @@
1
+ # {{PROJECT_NAME}}
2
+
3
+ Generated by **OBSESSION**. Stack: React + TypeScript + React Router + Redux Toolkit + RTK Query + Vite+.
4
+
5
+ ## Start
6
+
7
+ If dependencies were not installed automatically:
8
+
9
+ ```bash
10
+ npm install
11
+ ```
12
+
13
+ Then:
14
+
15
+ ```bash
16
+ npm exec -- vp dev
17
+ ```
18
+
19
+ To verify changes:
20
+
21
+ ```bash
22
+ npm run guard
23
+ npm run guard:test
24
+ npm exec -- vp check
25
+ npm exec -- vp test
26
+ npm exec -- vp build
27
+ ```
28
+
29
+ If global Vite+ (`vp`) is installed, use `vp dev`, `vp check`, `vp test`, and `vp build` directly.
30
+
31
+ ## Rules
32
+
33
+ - `src/app`: wiring only; no business logic.
34
+ - `src/features/<name>`: feature-owned UI, model, API, routes and types; external imports only through `index.ts`.
35
+ - `src/shared`: generic utilities and UI, no feature knowledge.
36
+ - Imports must point downward; no import cycles, including type-only cycles.
37
+ - Routes belong to features and are lazy-loaded.
38
+ - Client shared state goes in feature Redux slices; server data belongs to RTK Query feature endpoints.
39
+ - `.env` is local only. VITE_* variables are **public** in the browser; never put secrets here.
40
+
41
+ See `AGENTS.md` and `docs/FRONTEND_ARCHITECTURE.md` for the complete rules. The original user-provided architecture HTML is in `docs/reference/`.
42
+
43
+ ## Chapter 8-10 enforcement
44
+
45
+ - `vite.config.ts` contains Oxlint import boundaries, cycle checks, and TypeScript checks.
46
+ - `scripts/check-architecture.mjs` independently verifies resolved module boundaries and type-only cycles.
47
+ - `CLAUDE.md`, `AGENTS.md`, and `docs/TASK_PROTOCOL.md` enforce the agent's task-scope and recheck workflow.
48
+ - `npm run verify` runs the full verification chain. VS Code: Tasks > Run Task > **OBSESSION: Verify Entire Frontend**.
49
+ - See `docs/CHAPTER_8_9_10_ENFORCEMENT.md` for the mapping to the original architecture course.
50
+
51
+ ## OBSESSION v1.1 testing, scope and security
52
+
53
+ - `npm run verify` runs architecture tests, task-scope guard self-tests, Vite+ static/type checks, component tests, build and a high-severity npm audit (requires network and a lockfile).
54
+ - `npx playwright install chromium` downloads the optional E2E browser; `npm run test:e2e` tests the real browser. CI installs Chromium automatically.
55
+ - Before every coding task, start the scope with `npm run scope:start -- --id OB-123 --allow "src/features/home/**"`. After coding, run `npm run verify:task`; this rejects out-of-scope file edits.
56
+ - Features are intentionally flat: **no** `ui/components/` nesting. Separate large capabilities into sibling features with their own doors.
57
+ - See `docs/STATE_OWNERSHIP.md`, `docs/UI_STATES.md`, `docs/SECURITY_BASELINE.md`, `docs/TESTING_STRATEGY.md` and `docs/TASK_SCOPE.md`.
@@ -0,0 +1,82 @@
1
+ # Chapters 8, 9, 10 - Practical Enforcement Map
2
+
3
+ ## Chapter 8: Vite+ + Linter + Architecture Boundaries
4
+
5
+ `vite.config.ts` is the single Vite+ configuration root. It defines:
6
+
7
+ - React plugin (`@vitejs/plugin-react`)
8
+ - `@/` alias to `src/`, also mapped in `tsconfig.json`
9
+ - Oxlint built-in plugins: `import`, `typescript`, `react`
10
+ - `import/no-cycle` enabled as an error with `ignoreTypes: false`
11
+ - `no-restricted-imports`: errors for deep feature imports and forbidden upward imports
12
+ - `lint.overrides` for `src/features/**` and `src/shared/**`
13
+ - `lint.options.typeAware: true` and `typeCheck: true` so `vp check` checks types
14
+ - `test.include` for colocated `*.test.ts` and `*.test.tsx`
15
+
16
+ Run `npm exec -- vp check`. Never weaken checks to make CI green.
17
+
18
+ **Important difference from the original course:** Oxlint's native configuration is used rather than blindly copying an ESLint config. Specific regex restrictions and overrides are intended to match current Vite+ (Oxlint) syntax. After installing the actual toolchain, verify that the local installed version loads the configuration. The separate `node scripts/check-architecture.mjs` guard is mandatory even when lint succeeds.
19
+
20
+ ### Structural rule checker
21
+
22
+ `node scripts/check-architecture.mjs` resolves local imports and checks:
23
+
24
+ - Rule A: imports point downward, no shared -> feature/app and no feature -> app
25
+ - Rule B: cross-feature imports use `index.ts` door; cross-shared-section imports use section door
26
+ - Rule C: no import cycles (including type-only import edges)
27
+ - Model must not import UI; shared UI must not use Redux directly
28
+ - Feature and shared public doors exist
29
+ - Tests are colocated with matching module filenames
30
+
31
+ The checker also rejects nonliteral dynamic `import(expr)` and `require(expr)` because they bypass static verification. Such cases require explicit review and checker changes; do not add silent exceptions.
32
+
33
+ The checker is not a full TypeScript parser; dynamic module resolution, package code and runtime routing still require other tests. Type checking and CI remain necessary.
34
+
35
+ ## Chapter 9: Agent boundaries
36
+
37
+ - `CLAUDE.md`: entrypoint for Claude Code in VS Code.
38
+ - `AGENTS.md`: repository-wide, tool-agnostic rules.
39
+ - `docs/TASK_PROTOCOL.md`: mandatory before/during/after contract for every code task.
40
+ - Scope includes a list of allowed paths and any one-line `src/app` wiring exceptions.
41
+ - After a task, inspect the Git diff AND untracked files. Any surprise change is a failure requiring correction or explicit approval.
42
+ - All task status reports must distinguish PASS / FAIL / BLOCKED rather than claiming success.
43
+
44
+ The code agent can read these documents; these are instructions, not a technical sandbox. Independent boundary checking and CI enforce the machine-testable portion.
45
+
46
+ ## Chapter 10: Tests and recurring verification
47
+
48
+ - Add a colocated `SomeModule.test.ts` beside the changed `SomeModule.ts`.
49
+ - Starter: `src/features/counter/model/counterSlice.test.ts`.
50
+ - Keep UI, model, lib, API and routes tests aligned with their feature contracts.
51
+ - Check the guard itself with `npm run guard:test` (negative controls).
52
+ - `npm exec -- vp test` verifies observable behavior.
53
+ - `npm exec -- vp build` verifies production compilation.
54
+ - `.github/workflows/quality.yml` runs the same gates on GitHub push / pull request.
55
+ - `.vscode/tasks.json` exposes **OBSESSION: Verify Entire Frontend** in VS Code's Run Task menu.
56
+
57
+ ### Commands after every task
58
+
59
+ ```bash
60
+ npm run guard
61
+ npm run guard:test
62
+ npm exec -- vp check
63
+ npm exec -- vp test
64
+ npm exec -- vp build
65
+ # or: npm run verify
66
+ ```
67
+
68
+ ### Failure exercise
69
+
70
+ To verify the gate catches a bad import, do not damage the real repository. Run `npm run guard:test` (the test script makes temporary fixtures that intentionally break Rules A/B/C and asserts failures).
71
+
72
+ ## What cannot be enforced automatically
73
+
74
+ A linter cannot prove that code is genuinely business-neutral, that two features need a shared helper, that new behavior matches a Jira ticket, or that tests are sufficiently meaningful. These stay in the manual acceptance-criteria and PR-review gate.
75
+
76
+ ## Configuration references
77
+
78
+ - Vite+ lint: https://viteplus.dev/guide/lint
79
+ - Vite+ check: https://viteplus.dev/guide/check
80
+ - Vite+ test: https://viteplus.dev/guide/test
81
+ - Oxlint no-restricted-imports: https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-restricted-imports
82
+ - Oxlint import/no-cycle: https://oxc.rs/docs/guide/usage/linter/rules/import/no-cycle