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.
- package/LICENSE +21 -0
- package/README.md +160 -2
- package/bin/README.md +6 -0
- package/bin/obsession.exe +0 -0
- package/bin/obsession.out +0 -0
- package/frontend/README.md +41 -0
- package/frontend/project-type.json +8 -0
- package/frontend/template/.agent/task-scope.example.json +7 -0
- package/frontend/template/.editorconfig +11 -0
- package/frontend/template/.env +2 -0
- package/frontend/template/.env.example +2 -0
- package/frontend/template/.github/dependabot.yml +11 -0
- package/frontend/template/.github/workflows/quality.yml +28 -0
- package/frontend/template/.gitignore.tpl +28 -0
- package/frontend/template/.vscode/extensions.json +3 -0
- package/frontend/template/.vscode/settings.json +13 -0
- package/frontend/template/.vscode/tasks.json +39 -0
- package/frontend/template/AGENTS.md +56 -0
- package/frontend/template/CLAUDE.md +18 -0
- package/frontend/template/README.md.tpl +57 -0
- package/frontend/template/docs/CHAPTER_8_9_10_ENFORCEMENT.md +82 -0
- package/frontend/template/docs/FEATURE_BLUEPRINT.md +164 -0
- package/frontend/template/docs/FRONTEND_ARCHITECTURE.md +132 -0
- package/frontend/template/docs/SECURITY_BASELINE.md +32 -0
- package/frontend/template/docs/STATE_OWNERSHIP.md +33 -0
- package/frontend/template/docs/TASK_PROTOCOL.md +50 -0
- package/frontend/template/docs/TASK_SCOPE.md +35 -0
- package/frontend/template/docs/TECHNOLOGY_AND_CONFIG.md +96 -0
- package/frontend/template/docs/TESTING_AND_GATES.md +109 -0
- package/frontend/template/docs/TESTING_STRATEGY.md +34 -0
- package/frontend/template/docs/UI_STATES.md +26 -0
- package/frontend/template/docs/reference/front-end-structure-course.html +1606 -0
- package/frontend/template/docs/reference/frontend-project-setup-manual.docx +0 -0
- package/frontend/template/e2e/smoke.spec.ts +12 -0
- package/frontend/template/index.html.tpl +13 -0
- package/frontend/template/package.json.tpl +45 -0
- package/frontend/template/playwright.config.ts +18 -0
- package/frontend/template/scripts/check-architecture.mjs +291 -0
- package/frontend/template/scripts/check-architecture.test.mjs +93 -0
- package/frontend/template/scripts/task-scope.mjs +70 -0
- package/frontend/template/scripts/task-scope.test.mjs +46 -0
- package/frontend/template/src/app/NotFoundPage.tsx +5 -0
- package/frontend/template/src/app/RootLayout.tsx +15 -0
- package/frontend/template/src/app/RouteErrorBoundary.tsx +12 -0
- package/frontend/template/src/app/main.tsx +11 -0
- package/frontend/template/src/app/providers.tsx +12 -0
- package/frontend/template/src/app/router.tsx +14 -0
- package/frontend/template/src/app/store.ts +12 -0
- package/frontend/template/src/features/counter/index.ts +2 -0
- package/frontend/template/src/features/counter/model/counterSlice.test.ts +12 -0
- package/frontend/template/src/features/counter/model/counterSlice.ts +16 -0
- package/frontend/template/src/features/counter/model/selectors.ts +4 -0
- package/frontend/template/src/features/counter/ui/CounterWidget.tsx +16 -0
- package/frontend/template/src/features/home/index.ts +1 -0
- package/frontend/template/src/features/home/routes.tsx +8 -0
- package/frontend/template/src/features/home/ui/HomePage.test.tsx +11 -0
- package/frontend/template/src/features/home/ui/HomePage.tsx +13 -0
- package/frontend/template/src/shared/api/baseApi.ts +9 -0
- package/frontend/template/src/shared/api/index.ts +1 -0
- package/frontend/template/src/shared/config/env.ts +3 -0
- package/frontend/template/src/shared/config/index.ts +1 -0
- package/frontend/template/src/shared/ui/Button.tsx +6 -0
- package/frontend/template/src/shared/ui/StatusPanel.test.tsx +25 -0
- package/frontend/template/src/shared/ui/StatusPanel.tsx +36 -0
- package/frontend/template/src/shared/ui/index.ts +4 -0
- package/frontend/template/src/shared/ui/styles.css +27 -0
- package/frontend/template/src/vite-env.d.ts +1 -0
- package/frontend/template/tests/setup.ts +1 -0
- package/frontend/template/tsconfig.json +21 -0
- package/frontend/template/vite.config.ts +73 -0
- package/npm/cli.js +53 -0
- 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
|
-
#
|
|
1
|
+
# OBSESSION
|
|
2
2
|
|
|
3
|
-
|
|
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,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,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
|