diff --git a/BUILD-ENVIRONMENT.md b/BUILD-ENVIRONMENT.md deleted file mode 100644 index ca4a76d4..00000000 --- a/BUILD-ENVIRONMENT.md +++ /dev/null @@ -1,271 +0,0 @@ -# AyaNova v8 Build Environment Documentation - -> **Purpose**: This document captures the exact build environment for AyaNova v8 as of February 2026. Use this to recreate the build environment on a new machine or in a container. - -## Overview - -AyaNova v8 consists of three main build components: - -1. **Frontend** - Vue.js 2 application (JavaScript, not TypeScript) -2. **Documentation** - MkDocs with Material theme -3. **Backend** - ASP.NET Core 8.0 server (C#) - -The frontend and docs are built first, then copied into the backend project's `wwwroot` folder before the backend is built and packaged for distribution. - ---- - -## Current Build Machine Specifications - -| Component | Version | Notes | -|-----------|---------|-------| -| Operating System | Windows 11 | ThinkPad X13 Gen 3 | -| Node.js | v12.22.9 | **End-of-life** - do not upgrade without testing | -| npm | (check with `npm -v`) | Comes with Node | -| Python | 3.11.1 | For MkDocs | -| .NET SDK | 8.0.x | For backend build | - ---- - -## Frontend Build Environment - -### Directory Structure - -``` -c:\data\code\ -├── raven-client\ -│ └── ayanova\ # Vue.js frontend project -│ ├── src\ # Source code -│ ├── public\ # Static assets -│ ├── dist\ # Build output (generated) -│ ├── package.json -│ ├── vue.config.js -│ └── buildrelease.bat -├── raven\ -│ ├── server\ -│ │ └── AyaNova\ -│ │ └── wwwroot\ # Frontend files copied here after build -│ └── docs\ -│ └── 8.0\ -│ └── ayanova\ # MkDocs source -│ └── mkdocs.yml -``` - -### Node.js Version: Critical Information - -**Current version: Node.js 12.22.9** - -This project uses an old Node version because: - -1. The `fibers` package (used by sass-loader for faster Sass compilation) is a native C++ addon that stopped being maintained and doesn't compile on newer Node versions -2. Various other dependencies have peer dependency requirements that break on Node 14+ - -**Do not upgrade Node without first testing in an isolated environment.** - -### Key Dependencies - -From `package.json`: - -| Package | Version | Purpose | -|---------|---------|---------| -| vue | 2.6.14 | Core framework (Vue 2, end-of-life Dec 2023) | -| vuetify | 2.6.6 | UI component library | -| @vue/cli-service | 4.5.15 | Build tooling | -| webpack | 4.46.0 | Module bundler | -| sass | 1.52.3 | Sass compiler | -| fibers | 4.0.3 | **Problematic** - native addon for Sass | -| monaco-editor | 0.30.1 | Code editor component | - -### Build Process - -The frontend build is executed via `buildrelease.bat`: - -```batch -@echo ************************************************************** -@echo ******************** BUILD CLIENT **************************** -@echo ************************************************************** -rmdir c:\data\code\raven\server\AyaNova\wwwroot /s/q -mkdir c:\data\code\raven\server\AyaNova\wwwroot -cd c:\data\code\raven\docs\8.0\ayanova -mkdocs build -cd c:\data\code\raven-client\ayanova -call npm run build -xcopy c:\data\code\raven-client\ayanova\dist\* C:\data\code\raven\server\AyaNova\wwwroot\ /e -pause -``` - -This does: -1. Clears and recreates the backend's wwwroot folder -2. Builds the MkDocs documentation (output goes directly to wwwroot/docs via mkdocs.yml config) -3. Runs `npm run build` which calls `vue-cli-service build` -4. Copies the built frontend from `dist/` to the backend's `wwwroot/` - -### Known Build Warnings (Safe to Ignore) - -These warnings appear during every build and do not affect the output: - -1. **Browserslist warning**: "caniuse-lite is outdated" - - Harmless - just means browser compatibility database is old - -2. **Dart Sass division warnings**: "Using / for division is deprecated" - - Come from Vuetify's stylesheets, not your code - - Will continue working until Dart Sass 2.0 - -3. **Asset size warnings**: Various files exceed 244 KiB - - Expected with Monaco editor (ts.worker.js is 4.5MB) - - Application still works correctly - -### NPM Scripts - -```json -{ - "serve": "vue-cli-service serve", // Development server - "build": "vue-cli-service build", // Production build - "lint": "vue-cli-service lint" // Code linting -} -``` - ---- - -## Documentation Build Environment - -### MkDocs Configuration - -From `mkdocs.yml`: - -| Setting | Value | -|---------|-------| -| Theme | Material | -| Output directory | `../../../server/AyaNova/wwwroot/docs` | -| Site URL | https://ayanova.com/docs/ | - -### Required Python Packages - -```bash -pip install mkdocs mkdocs-material -``` - -The `pymdownx` extensions (highlight, superfences) come bundled with mkdocs-material. - -### Build Command - -```bash -cd c:\data\code\raven\docs\8.0\ayanova -mkdocs build -``` - -Output goes directly to the backend's wwwroot/docs folder. - ---- - -## Backend Build Environment - -### .NET Version - -- **Target Framework**: .NET 8.0 -- **Project Type**: ASP.NET Core - -### Build Tools Required - -- .NET 8.0 SDK -- Visual Studio 2022 or VS Code with C# extension - -### Build Outputs - -The backend build produces multiple deployment targets: -1. Linux hosted (DigitalOcean service) -2. Windows networked (IIS hosted) -3. Windows single-user (self-contained) -4. Linux server -5. Linux desktop - -Windows installers are created with Inno Setup. - ---- - -## Recreating the Build Environment - -### Option 1: Native Installation (Windows) - -1. Install Node.js 12.22.9 specifically: - - Download from https://nodejs.org/dist/v12.22.9/ - - Or use nvm-windows: `nvm install 12.22.9 && nvm use 12.22.9` - -2. Install Python 3.11: - - Download from python.org - - Ensure it's in PATH - -3. Install MkDocs: - ```bash - pip install mkdocs mkdocs-material - ``` - -4. Install .NET 8.0 SDK: - - Download from https://dotnet.microsoft.com/download - -5. Clone/checkout repository from SVN - -6. Install frontend dependencies: - ```bash - cd c:\data\code\raven-client\ayanova - npm ci - ``` - Note: Use `npm ci` (not `npm install`) to install exact versions from package-lock.json - -### Option 2: Docker (Recommended for Reproducibility) - -See `Dockerfile.frontend` and `Dockerfile.docs` in this repository for containerized builds that don't require any local installation except Docker. - ---- - -## Troubleshooting - -### "fibers" fails to install - -This native module requires: -- Python 2.7 or 3.x -- Visual Studio Build Tools (Windows) or build-essential (Linux) -- Specific Node.js version compatibility - -If it fails, you can try removing it (it's optional): -1. Remove `"fibers": "^4.0.3"` from package.json -2. Remove the `fiber: require("fibers")` line from webpack.config.js -3. Run `npm install` again - -The build will be slightly slower but should work. - -### Node version mismatch - -If you see errors about incompatible Node versions: -1. Check your Node version: `node -v` -2. It must be 12.22.9 for guaranteed compatibility -3. Use nvm to switch versions if needed - -### "Module not found" errors - -Try: -```bash -rm -rf node_modules -rm package-lock.json -npm install -``` - ---- - -## Future Modernization Notes - -When time permits, consider: - -1. **Remove fibers dependency** - It's optional and causes most build issues -2. **Upgrade to Vue 3 + Vite** - Much faster builds, better tooling, active support -3. **Migrate to TypeScript** - Better IDE support and fewer runtime errors -4. **Update Node to LTS** - Current LTS is Node 20.x - -These are significant changes that should be done incrementally with thorough testing. - ---- - -## Version History - -| Date | Change | -|------|--------| -| 2026-02-01 | Initial documentation created | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..d1d778b2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# AyaNova v8 front end — instructions for Claude Code + +Shared AyaNova context and working rules, from the server repo (the master): +@../raven/CLAUDE.md + +Everything below is specific to this repo. + +## What this is + +The AyaNova v8 web client, in `ayanova/`. Vue 2.6, Vuetify 2.6, Vuex, Vue Router, plain +JavaScript (no TypeScript), Vue CLI 4 / webpack 4. Stack details: +`../raven/devdocs/modernization/CODEBASE-REFERENCE.md`. + +## During the .NET 10 port + +The port is back-end only. **No changes in this repo** unless John asks, apart from a +rebuild if the port needs one. Whether the client gets rebuilt in this pass is an open +question in `../raven/devdocs/modernization/NET10-PORT.md`. + +If a port item touches the client (for example removing a package from both repos), it +goes on a `net10-port` branch here too, with its own commit. + +## Constraints + +- **Node.js 12.22.9 exactly.** `fibers` breaks on anything newer. Check with `node -v` before building. +- **No dependency changes**: no `npm install `, no `npm update`, no version edits in `package.json`. Front-end upgrades are roadmap step F, not current work. +- Install with `npm ci` (exact versions from `package-lock.json`), never `npm install`. +- Vue 2 / Vuetify 2 are end of life. Do not upgrade them, and do not write Vue 3 style code. +- Add `data-testid` attributes to elements that Cypress tests select. + +## Commands + +```powershell +cd ayanova +npm ci # first time, or after package-lock.json changes +npm run serve # dev server with hot reload +npm run build # production build into dist\ +npm run lint +``` + +## How the build reaches the server + +`npm run build` writes to `ayanova\dist\`. `raven\build-release.bat` (or `buildrelease.bat` +here) copies it into `raven\server\AyaNova\wwwroot\`. The .NET build does not produce +`wwwroot`: whatever is there when the server is published is what ships. + +Webpack content-hash file names (`app..js` …) change on every build even when the +contents do not. Compare file contents, not names. + +Warnings on every build that are harmless: Browserslist "caniuse-lite is outdated"; Dart +Sass division deprecation (from Vuetify); asset size (Monaco's workers). + +## Code layout + +`src/api/` API utilities, auth and error handling; `src/components/` about 80 components; +`src/views/` about 100 pages; `src/plugins/` Vuetify setup; `router.js`, `store.js`, +`main.js`, `App.vue`. + +View prefixes: `acc-` accounting, `adm-` administration, `cust-` customers, `home-` +dashboard, `inv-` inventory, `ops-` server operations, `svc-` service (work orders, quotes, +PMs).