Refactor code structure for improved readability and maintainability; remove redundant code blocks and optimize function calls.

docs/yarn-basics-cheatsheet.md

@@ -0,0 +1,191 @@
+# Yarn Basics Cheat Sheet (Beginner)
+
+This page explains Yarn from zero and gives a short command set you can use daily.
+
+## 1) What Yarn Is
+
+Yarn is a JavaScript/TypeScript package manager.
+
+It helps you:
+
+- Install libraries your project depends on.
+- Keep dependency versions consistent.
+- Run scripts defined by the project.
+- Work with private package registries.
+
+## 2) Core Concepts
+
+### Package
+
+A package is reusable code published to a registry (for example npm or your company Gitea registry).
+
+Example in this project context:
+
+- `@jig-software/trest`
+
+### Dependency
+
+A dependency is a package your app needs to run.
+
+- Regular dependency: needed at runtime.
+- Dev dependency: needed for development/testing only.
+
+### package.json
+
+This file declares project metadata and dependencies.
+
+### yarn.lock
+
+This lock file pins exact dependency versions to keep installs reproducible across machines and CI.
+
+### Registry
+
+A registry is where packages are downloaded from.
+
+- Public: npmjs
+- Private: your company Gitea Packages endpoint
+
+### Scope
+
+A scope is a package namespace like `@jig-software`.
+
+A scope can be routed to a custom registry in `.yarnrc.yml`.
+
+### .yarnrc.yml
+
+Project-level Yarn config. It controls behavior such as:
+
+- Registry URLs
+- Authentication token source
+- Install/link strategy
+
+### PnP (Plug'n'Play)
+
+PnP is Yarn's alternative to `node_modules`.
+
+- Faster and stricter dependency resolution.
+- Dependencies are mapped through `.pnp.cjs`.
+- Some tools that assume `node_modules` may need extra config.
+
+## 3) How Your Current .yarnrc.yml Works
+
+From this repo config:
+
+- `nodeLinker: pnp` means no traditional `node_modules` tree.
+- `npmScopes.jig-software` routes `@jig-software/*` packages to Gitea.
+- `npmAuthToken` reads token from env var `JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN`.
+- `npmAlwaysAuth: true` always sends auth to that private registry.
+
+## 4) 8 Commands You Need Day-to-Day
+
+1. Check Yarn version
+
+```bash
+yarn --version
+```
+
+2. Install all dependencies from lockfile
+
+```bash
+yarn install
+```
+
+3. Add a dependency
+
+```bash
+yarn add <package-name>
+```
+
+4. Add a dev dependency
+
+```bash
+yarn add -D <package-name>
+```
+
+5. Remove a dependency
+
+```bash
+yarn remove <package-name>
+```
+
+6. Run a package script
+
+```bash
+yarn <script-name>
+```
+
+7. Inspect package info in registry
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+8. Install trest from private scope
+
+```bash
+yarn add @jig-software/trest
+```
+
+## 5) Private Registry Quick Start (This Company)
+
+1. Export token in shell:
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
+```
+
+2. Verify package access:
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+3. Install package:
+
+```bash
+yarn add @jig-software/trest
+```
+
+## 6) Common Errors and Fixes
+
+### Error: 401 Unauthorized
+
+Likely causes:
+
+- Missing or expired token.
+- Wrong token scopes.
+
+Fix:
+
+- Re-export token and retry.
+- Regenerate PAT with package read access.
+
+### Error: 404 on whoami
+
+Some Gitea npm endpoints do not support whoami.
+
+Fix:
+
+- Use `yarn npm info @jig-software/trest` as the verification command.
+
+### Error: tool expects node_modules
+
+Cause:
+
+- Project uses PnP.
+
+Fix:
+
+- Configure that tool for PnP, or switch linker mode for that project if approved by the team.
+
+## 7) Mental Model
+
+Use this flow every time:
+
+1. package.json asks for packages.
+2. yarn.lock pins exact versions.
+3. .yarnrc.yml tells Yarn where/how to fetch.
+4. Yarn installs and links dependencies (PnP here).
+5. Scripts run with the installed dependency graph.
+
+If one step fails, debug that layer first.