---
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 Request Network webhooks on your laptop.

**When to run.** Local Request Network 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.** Historical sanity check for the old SHKeeper service.

**When to run.** Legacy-record troubleshooting only; new payment work should use the Request Network tests.

**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. Treat this as a legacy/manual helper; routine releases should go through ledger-gated release/refund orchestration.

### `fix-transaction-hashes.js`

**Purpose.** Historical one-off backfill — walks completed legacy Payments missing `transactionHash`, queries SHKeeper for the original invoice, extracts the confirmed transaction hash, and updates the payment document.

**When to run.** Only for old SHKeeper records. New Request Network payments should be reconciled through Request Network webhook/reconciliation tooling.

**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 legacy 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
```