nick-doc/07 - Development/Scripts.md

title, tags

title	tags
Scripts	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.

./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.

./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.

./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.

./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.

./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.

./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.

./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.

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.

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.

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.

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.

# 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.

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.

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

# === 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