golid / rules

---
description: Patterns for the project rename tool — file coverage, domain-safe replacement, name validation
globs: backend/cmd/rename/*.go
alwaysApply: false
---

# Rename Tool Patterns

> **Thesis:** A missed file means a downstream user ships with the wrong brand. A naive replacement corrupts domain URLs. Every rename must be domain-safe and total.

The rename tool (`make rename` / `go run ./cmd/rename`) rebrands the entire project. It's high-risk — a missed file means a downstream user ships with "Golid" in their app, and a naive replacement corrupts domain URLs.

## CLI

```bash
go run ./cmd/rename <name> <module-path> [new-domain] [--strict] [--starter-copy-hint]
make rename name=myapp module=github.com/user/myapp/backend domain=myapp.com
```

- **`new-domain`** — replaces `golid.ai` / `https://golid.ai` fallbacks; prints prod env checklist.
- **`--strict`** — exit non-zero if survivor scan finds leftover `golid` in shipped paths.
- **`--starter-copy-hint`** — lists files with starter marketing copy to rewrite manually.

## Domain-Safe Replacement

`replaceInFileSafe` uses a null-byte placeholder to protect the project domain (`golid.ai`) from corruption. Without it, `"golid"→"myapp"` turns `golid.ai` into `myapp.ai`.

```go
const placeholder = "\x00DOMAIN\x00"
protected := strings.ReplaceAll(content, oldDomain, placeholder)
updated := strings.ReplaceAll(protected, old, new)
final := strings.ReplaceAll(updated, placeholder, oldDomain)
```

Use `replaceInFileSafe` for any file that might contain the project domain (docker-compose, deploy scripts, env files, infra templates, CI configs). Use `replaceInFile` for files that only contain module paths or titled names (Go imports, package.json scope). When `[new-domain]` is passed, run a separate `replaceDomain` pass with plain `replaceInFile` on domain-bearing paths.

## Self-preservation

**Never edit `backend/cmd/rename/main.go`.** Skip the file entirely in the Go walk so baseline `oldModule` / `oldProjectName` constants survive fork renames.

## File Coverage

The tool must cover every file with hardcoded project names. Current categories:

| # | Target | Function |
|---|--------|----------|
| 1 | `go.mod` | Module path |
| 2 | All `.go` except `cmd/rename/main.go` | Import paths + titled + safe lowercase |
| 3 | `docker-compose.yml` | Container/DB names |
| 4 | `package.json` + lock | npm scope |
| 5 | `README.md` | GitHub repo + titled + safe lowercase (tree paths) |
| 6 | `.cursor/rules/*.mdc` | Module path + titled + project name |
| 7 | `docs/**/*.md` except `decisions/`, `plans/archive/` | Module + safe lowercase + titled |
| 8 | `frontend/src/**/*.{ts,tsx}` | Titled + safe lowercase + all-caps |
| 8b | `frontend/src/**/*.css` | Branded class names |
| 8c | `frontend/tests/**/*.{ts,tsx}` | Same as src (e2e + unit URLs/headings) |
| 9 | Community files + `CODE_OF_CONDUCT.md` (if present) | GitHub + titled + safe lowercase |
| 9b | `.github/ISSUE_TEMPLATE/*.md` | GitHub + titled + safe lowercase |
| 10 | `codecov.yml` | Module path |
| 11 | All `config/.env.*` via glob | APP_NAME + DB names (warn if `.env.local` missing) |
| 12 | `scripts/*.sh` + `scripts/README.md` | Project name + titled (`setup-domain.sh`, `init-test-db.sh`) |
| 13 | Swagger docs, DevContainer, Dockerfiles | Titled + project name |
| 14 | `infra/**/*.yaml` + `.github/workflows/*.yml` | Safe lowercase + titled (descriptions) |
| 15 | Scaffold template + backend Makefile | Titled name |
| 16 | `testutil/testutil.go` | Default DB name |
| 17 | Entrypoint scripts | Project + titled name |
| 18 | `openapi.yaml` | Titled + project name |
| 19 | `.gitignore` | All-caps project name in comments |
| 20 | CI overlay, dev tooling, drift scripts | Safe + titled where branded |
| 21 | `[new-domain]` pass | `og-meta.tsx`, `entry-server.tsx`, tests, `setup-domain.sh`, README link |
| 22 | Public assets | Rename `golid-og.png` / `meta.png` when present; warn on favicons |

**When adding a new file with hardcoded project names**, add a corresponding replacement step here. Check lowercase, titled, and all-caps variants as appropriate.

## Name Validation

Project names must match `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` (2-50 chars). Domains must be bare hostnames (no `https://`).

## Post-rename verification

The tool prints a survivor scan and expanded checklist. Always verify:

1. `cd backend && go test ./cmd/rename/...`
2. `cd backend && go build ./...`
3. `cd frontend && npm run typecheck && npm run build`
4. `git diff` — use `--strict` before commit when automating
5. Set `config/.env.prod`: `FRONTEND_URL`, `ALLOWED_ORIGINS`, `VITE_OG_URL`, `GCP_PROJECT_ID`
6. Rewrite starter copy (`entry-server.tsx`, `og-meta.tsx`, landing page, e2e headings)
7. `./scripts/deploy.sh check prod` before first prod deploy