nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Initial commit: nick docs

Browse Source
This commit is contained in:
moojttaba
2026-05-23 20:35:34 +03:30
commit 0da235ae27
90 changed files with 18268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
07 - Development/Scripts.md Normal file
View File

@@ -0,0 +1,365 @@
---
title: Scripts
tags: [development]
---
# Scripts
A catalogue of every operational script across both repos. For each: **purpose**, **when to run**, and an **example invocation**. Scripts that touch the database have warnings.
> [!warning] Many of these scripts mutate live data (drop collections, push Docker tags, force version bumps). Read the script before running it on anything that matters.
---
## Backend — `backend/scripts/` (shell)
These shell scripts orchestrate the dev/build/release pipeline. They live next to the repo root and assume the repo is the current working directory.
### `auto-version.sh`
**Purpose.** Bump the `version` in `package.json` and create a matching git tag. Has an `auto` mode that asks `ai-enhanced.sh` to suggest the bump from the last commit message.
**When to run.** Before pushing a release. The `release:*` npm scripts call this for you.
**Example.**
```bash
./scripts/auto-version.sh patch # 2.6.3 → 2.6.4
./scripts/auto-version.sh minor # 2.6.3 → 2.7.0
./scripts/auto-version.sh major # 2.6.3 → 3.0.0
./scripts/auto-version.sh auto # let the AI decide
./scripts/auto-version.sh help
# or via npm wrappers:
npm run version:patch
npm run release:minor
npm run smart-release # auto + push + push --tags
```
The script creates a commit `chore: bump version to <v>` and tag `v<version>`.
> [!warning] Make sure your working tree is clean and on the branch you want tagged. The script will not stash changes.
---
### `ai-enhanced.sh`
**Purpose.** Analyse a commit message (last commit by default) against rules in `ai-rules.conf` and recommend `major`/`minor`/`patch`/`skip` plus a confidence level. Used by `auto-version.sh auto`.
**When to run.** Standalone diagnostic before a release; otherwise invoked indirectly.
**Example.**
```bash
./scripts/ai-enhanced.sh # analyse last commit
./scripts/ai-enhanced.sh "feat: add seller payouts" # analyse a string
npm run ai:detect
```
Exports `AI_VERSION_TYPE` and `AI_CONFIDENCE` for downstream scripts.
---
### `build-and-push.sh`
**Purpose.** Build the production Docker image (`Dockerfile.prod`) tagged with `dev-<package-version>` plus `latest`, then push to the Gitea registry.
**When to run.** For a manual dev release outside of CI. CI does the same thing automatically — see [[CI-CD Pipeline]].
**Example.**
```bash
./scripts/build-and-push.sh
```
You must `docker login git.manko.yoga -u manawenuz` first. Pushes both tags and asks whether to clean up the local images afterwards.
---
### `build-and-push-dev.sh`
**Purpose.** Variant of `build-and-push.sh` that tags only with the `dev-*` tag (no `latest`). Used when you want Watchtower to leave production untouched.
**When to run.** Manual dev-only push.
**Example.**
```bash
./scripts/build-and-push-dev.sh
```
---
### `build-image.sh`
**Purpose.** Local-only build (no push). Tags `<registry>/<image>:<version>` and `:latest`. Useful for testing the production Dockerfile locally without sending it anywhere.
**When to run.** Verifying a `Dockerfile.prod` change before pushing.
**Example.**
```bash
./scripts/build-image.sh
```
---
### `reset-server.sh`
**Purpose.** Stop the dev compose stack, restart it fresh, wait for services, then probe MongoDB, Redis, `/health`, and the login endpoint. Prints the seeded test credentials at the end.
**When to run.** When your local containers are in a weird state, or after pulling new images.
**Example.**
```bash
./scripts/reset-server.sh
```
> [!warning] By default this preserves volumes. To wipe the database, edit the script to uncomment `docker-compose ... down -v` or run that command manually first.
---
### `start-ngrok.sh`
**Purpose.** Start `ngrok http` against a local port (default `8083`) and print the public URL by polling the inspector at `127.0.0.1:4040`. Lets you receive SHKeeper webhooks on your laptop.
**When to run.** Local SHKeeper webhook development.
**Example.**
```bash
./scripts/start-ngrok.sh 5001 # tunnel to backend
./scripts/start-ngrok.sh # tunnel to default 8083
REGION=eu ./scripts/start-ngrok.sh
```
Logs go to `~/.ngrok-<port>.log` and the pid to `~/.ngrok-<port>.pid`. Requires `brew install ngrok` and `ngrok config add-authtoken <token>`.
---
### `fix-dispute-sellers.js`
**Purpose.** One-off Node script that walks the `disputes` collection and back-fills missing `sellerId` fields by joining through `purchaseRequests` + `sellerOffers`. Born from a real-world data-quality bug.
**When to run.** Only if disputes appear in admin UI without a seller. Otherwise: never.
**Example.**
```bash
MONGODB_URI=mongodb://localhost:27017/marketplace node ./scripts/fix-dispute-sellers.js
```
> [!warning] Mutates dispute documents. Take a backup first ([[Backup & Recovery]]).
---
## Backend — `backend/src/scripts/` (TypeScript + helpers)
These are runnable with `ts-node`. The `npm run seed:*` entries wrap the most common ones.
### Seed scripts
| Script | npm wrapper | Purpose |
|--------|-------------|---------|
| `seedUsers.ts` | `npm run seed:users` | Create the four canonical test users (admin, buyer, seller, seller2). Idempotent: skips users that already exist. |
| `seedAddresses.ts` | `npm run seed:addresses` | Wipe and re-create sample addresses for the test users (max 3 per user, primary flag set). **Requires users to exist.** |
| `seedUsersAndAddresses.ts` | `npm run seed:all` | Combined: drops and recreates users + addresses in the right order. The canonical "fresh database" command. |
| `seedCategories.ts` | `npm run seed:categories` | Insert the marketplace category tree. Idempotent. |
| `seeds/seedRequestTemplates.ts` | manual | Seed example request templates buyers can use as starting points. |
| `seeds/seedBlogPosts.ts` | manual | Seed sample blog content. |
| `seeds/seedLevels.ts` | manual | Insert level config for the points/reputation system. |
| `seeds/migrateUserPoints.ts` | manual | One-shot migration of legacy point balances. |
**Example.**
```bash
npm run seed:all
npm run seed:categories
ts-node src/seeds/seedRequestTemplates.ts
```
> [!warning] `seed:addresses` and `seed:all` drop existing data. Don't run against production unless that is what you want.
### Other TS helpers
| Script | Purpose |
|--------|---------|
| `clearCategories.ts` | Wipe the `categories` collection (paired with `seedCategories.ts`). |
| `clearChats.ts` | Wipe the `chats` collection. Useful in QA. |
| `createSupportUser.ts` | Create the marketplace support user (used in chat). |
| `createTestMessage.ts` | Insert a single test chat message between buyer and seller. |
| `createTestRequest.ts` | Create a sample purchase request from the seeded buyer. |
| `updateCategories.ts` | Apply schema updates to existing categories without re-seeding. |
| `updateRequestStatus.ts` | Force-set the `status` field of a purchase request — useful when QA-ing a flow. |
| `makeUserAdmin.ts` | Promote a user to admin. Pass email as an arg. |
| `createDemoShops.ts` | Generate demo seller shops for screenshots / staging. |
**Example.**
```bash
ts-node src/scripts/makeUserAdmin.ts user@example.com
ts-node src/scripts/createTestRequest.ts
ts-node src/scripts/updateRequestStatus.ts <requestId> completed
```
### Bash helpers under `src/scripts/`
These call the API with `curl` to drive larger demo-data flows:
- `createDemoTemplates.sh`, `createDemoWithPicsum.sh`, `createFullDemo.sh`, `createProductionTemplates.sh` — populate templates with placeholder data
- `deleteSellerTemplates.sh` — wipe templates owned by a given seller
- `updateShopImages.sh` — bulk-update shop images
Each script takes a base URL + admin token. Inspect them before running.
---
## Backend — root-level helpers
### `manual-test.ts`
**Purpose.** Local sanity check for the SHKeeper service: calls `createPayInIntent` with mock data and verifies a webhook signature in dev mode.
**When to run.** Smoke-test after changing SHKeeper code without running the full suite.
**Example.**
```bash
ts-node manual-test.ts
```
### `manual-payout-test.ts`
**Purpose.** POST `/api/payments/payout` to the local backend with hard-coded payout data, then poll status after 5 s.
**When to run.** End-to-end payout flow check against a running local server.
**Example.**
```bash
# Backend must be running first:
npm run dev &
ts-node manual-payout-test.ts
```
> [!warning] Will create a real payout record in the DB. With `SHKEEPER_FORCE_PAYOUT_DEMO=true` no on-chain transaction is sent; without that flag a real on-chain transfer can occur.
### `fix-transaction-hashes.js`
**Purpose.** One-off backfill — walks completed Payments missing `transactionHash`, queries SHKeeper for the original invoice, extracts the confirmed transaction hash, and updates the payment document.
**When to run.** Only if you see payments displayed as "completed" with a missing tx hash. Rate-limits itself with a 1s delay per record.
**Example.**
```bash
MONGODB_URI=mongodb://localhost:27017/marketplace \
SHKEEPER_BASE_URL=https://shkeeper.example.com \
SHKEEPER_API_KEY=... \
node fix-transaction-hashes.js
```
> [!warning] Hits the live SHKeeper API and writes to MongoDB. Take a backup ([[Backup & Recovery]]).
### `check-templates.js`, `get-admin-token.js`
Diagnostic helpers. `check-templates.js` lists templates in the DB; `get-admin-token.js` logs in as the seeded admin and prints the JWT.
---
## Frontend — `frontend/scripts/`
### Deployment
| Script | Purpose | When |
|--------|---------|------|
| `deploy.sh` | Build production image, tag with package version + `latest`, push to Gitea registry. Triggered by Gitea Actions (`deploy.yml`) on push to `main`. | Production release. |
| `deployDev.sh` | Same as `deploy.sh` but pushes only the `dev` tag. Triggered by `devDeploy.yml` on push to `development`. | Dev release. |
### Versioning
| Script | Purpose |
|--------|---------|
| `auto-version.sh` | Mirror of backend `auto-version.sh` for the frontend. |
| `ai-enhanced.sh` | Mirror of backend AI version detector. Reads `ai-rules.conf`. |
| `ai-version-detect.sh` | Legacy / simpler version detector kept for fallback. |
| `setup-versioning.sh` | One-shot setup: installs a `post-commit` git hook that prints the recommended version bump. |
| `post-commit-hook.sh` | The hook installed by `setup-versioning.sh`. |
### Debugging & maintenance
| Script | Purpose |
|--------|---------|
| `debug-env.sh` | Print every `NEXT_PUBLIC_*` env var currently exported. |
| `debug-ui-api.sh` | Curl the backend health, auth, and a handful of marketplace endpoints; reports each. |
| `cleanup-docker-networks.sh` | Prune dangling Docker networks left behind by failed compose runs. |
| `show-credentials.sh` | Print the seeded test credentials (admin/buyer/seller). |
| `find-console-logs.sh` | List every `console.log/info/warn/error` left in `src/`. |
| `clean-console-logs.sh` | Auto-remove or comment out console logs. |
| `migrate-all-console-logs.sh` | Convert `console.*` calls to `logger.*`. Read `migrate-to-logger.md` before running. |
### Testing helpers
| Script | Purpose |
|--------|---------|
| `quick-test-suite.sh` | Run a curated subset of Jest + Playwright tests for a fast PR check. |
| `integration-test.sh` | Heavier scripted integration run against a live backend. |
| `test-marketplace-workflow.js` | Node script that drives a buyer → seller → checkout → payout flow via the API. |
| `test-offer-rejection.js` | Reproduce the offer-rejection bug pattern; useful for regression checks. |
**Examples.**
```bash
yarn ./scripts/debug-env.sh
./scripts/debug-ui-api.sh http://localhost:5001
./scripts/quick-test-suite.sh
node ./scripts/test-marketplace-workflow.js
```
---
## Frontend — root-level helpers
### `cleanup-localstorage.js`
**Purpose.** Browser console snippet — paste into DevTools to clear stale `manual-payment-*`, `buyer-step-*`, `LAST_PAYMENT_*`, `LAST_TEMPLATE_*`, and `LAST_SOCKET_*` keys from `localStorage`.
**When to run.** When QA reports state-related glitches that disappear in incognito.
**Example.** Paste the entire file body into the browser console and press Enter.
---
## Summary cheat-sheet
```bash
# === Backend ===
npm run dev # local node, no docker
npm run docker:dev # full stack in docker
npm run docker:dev:down # tear it down
npm run docker:dev:logs # follow logs
npm run seed:all # reset users + addresses (DESTRUCTIVE)
npm run seed:categories # idempotent
npm run test # jest
npm run test:coverage # + coverage
./scripts/reset-server.sh # nuke and rebuild dev compose
npm run release:patch # bump + commit + tag + push
npm run smart-release # AI-decided bump + push
./scripts/build-and-push.sh # manual docker push (dev tag)
# === Frontend ===
yarn dev # next dev on 8083
yarn build && yarn start # production-mode locally
yarn test # jest
yarn test:e2e # playwright
./scripts/deploy.sh # manual prod deploy push
./scripts/debug-ui-api.sh # curl smoke tests
```