From 9bb0a18695b7440643becf0a8f544456b38664c1 Mon Sep 17 00:00:00 2001 From: "D. Rimron-Soutter" Date: Sat, 10 Jan 2026 22:52:27 +0000 Subject: [PATCH] Update setup docs and scripts Refresh setup docs, add ZXDB local setup script, and note deploy rules. Signed-off-by: codex@lucy.xalior.com --- AGENTS.md | 5 +++++ README.md | 7 +++++++ bin/deploy.sh | 4 ++++ bin/setup-zxdb-local.sh | 18 ++++++++++++++++++ docs/ZXDB.md | 23 ++++++++++++++++------- docs/getting-started.md | 12 ++++++++++-- docs/index.md | 1 + package.json | 1 + 8 files changed, 62 insertions(+), 9 deletions(-) create mode 100755 bin/setup-zxdb-local.sh diff --git a/AGENTS.md b/AGENTS.md index 7d2b7fd..de5c2ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,6 +158,11 @@ Comment what the code does, not what the agent has done. The documentation's pur - Call out what to inspect visually (e.g., section names, table columns, empty states). - Use the local `.env` for any environment-dependent behavior. - Provide fully clickable links when sharing validation URLs. +- submodule hygiene: + - The `ZXDB` submodule is read-only in this repo; do not commit SQL dumps from it. + - Use `bin/setup-zxdb-local.sh` (or `pnpm setup:zxdb-local`) to add local excludes for SQL files. +- deploy workflow: + - `bin/deploy.sh` refuses to run with uncommitted or untracked files at the repo root. ### References diff --git a/README.md b/README.md index e72f90f..02175ee 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,9 @@ Project scripts (package.json) - `dev`: `PORT=4000 next dev --turbopack` - `build`: `next build --turbopack` - `start`: `next start` +- `deploy`: merge current branch into `deploy` and push to `explorer.specnext.dev` +- `deploy:branch`: same as `deploy`, but accepts a deploy branch argument +- `setup:zxdb-local`: configure local submodule excludes for ZXDB SQL files - `deploy-test`: push to `test.explorer.specnext.dev` - `deploy-prod`: push to `explorer.specnext.dev` @@ -59,6 +62,10 @@ The Registers section works without any database. The ZXDB Explorer requires a M 3) Run the app - `pnpm dev` → open http://localhost:4000 and navigate to `/zxdb`. +4) Keep the ZXDB submodule clean (recommended) +- Run `pnpm setup:zxdb-local` once after cloning. +- This keeps `ZXDB/ZXDB_mysql.sql` and `ZXDB/ZXDB_mysql_STRUCTURE_ONLY.sql` available locally without appearing as untracked changes. + API (selected endpoints) - `GET /api/zxdb/search?q=...&page=1&pageSize=20&genreId=...&languageId=...&machinetypeId=...&sort=title&facets=1` - `GET /api/zxdb/entries/[id]` diff --git a/bin/deploy.sh b/bin/deploy.sh index 9d20cad..f55a51a 100755 --- a/bin/deploy.sh +++ b/bin/deploy.sh @@ -8,6 +8,10 @@ if ! git diff --quiet || ! git diff --cached --quiet; then echo "Working tree is not clean. Commit or stash changes before deploy." exit 1 fi +if git ls-files --others --exclude-standard | grep -q .; then + echo "Untracked files present. Commit or remove them before deploy." + exit 1 +fi cleanup() { git checkout "${current_branch}" >/dev/null 2>&1 || true diff --git a/bin/setup-zxdb-local.sh b/bin/setup-zxdb-local.sh new file mode 100755 index 0000000..de064d3 --- /dev/null +++ b/bin/setup-zxdb-local.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +set -euo pipefail + +git_dir="$(git -C ZXDB rev-parse --git-dir)" +exclude_file="${git_dir}/info/exclude" + +mkdir -p "$(dirname "${exclude_file}")" +touch "${exclude_file}" + +add_exclude() { + local pattern="$1" + if ! grep -Fxq "${pattern}" "${exclude_file}"; then + printf "%s\n" "${pattern}" >> "${exclude_file}" + fi +} + +add_exclude "ZXDB_mysql.sql" +add_exclude "ZXDB_mysql_STRUCTURE_ONLY.sql" diff --git a/docs/ZXDB.md b/docs/ZXDB.md index 3d66f14..88e4538 100644 --- a/docs/ZXDB.md +++ b/docs/ZXDB.md @@ -4,13 +4,14 @@ This document explains how the ZXDB Explorer works in this project, how to set u ## What is ZXDB? -ZXDB ( https://github.com/zxdb/ZXDB )is a community‑maintained database of ZX Spectrum software, publications, and related entities. In this project, we connect to a MySQL ZXDB instance in read‑only mode and expose a fast, cross‑linked explorer UI under `/zxdb`. +ZXDB (https://github.com/zxdb/ZXDB) is a community‑maintained database of ZX Spectrum software, publications, and related entities. In this project, we connect to a MySQL ZXDB instance in read‑only mode and expose a fast, cross‑linked explorer UI under `/zxdb`. ## Prerequisites - MySQL server with ZXDB data (or at minimum the tables; data is needed to browse). - Ability to run the helper SQL that builds search tables (required for efficient LIKE searches). - A read‑only MySQL user for the app (recommended). +- The `ZXDB` submodule is checked in for schemas/scripts; use `pnpm setup:zxdb-local` after cloning to keep local SQL dumps untracked. ## Database setup @@ -19,7 +20,8 @@ ZXDB ( https://github.com/zxdb/ZXDB )is a community‑maintained database of ZX 2. Create helper search tables (required). - Run `https://github.com/zxdb/ZXDB/blob/master/scripts/ZXDB_help_search.sql` on your ZXDB database. - - This creates `search_by_titles`, `search_by_names`, `search_by_authors`, and `search_by_publishers` tables. + - This creates `search_by_titles`, `search_by_names`, `search_by_authors`, `search_by_publishers`, `search_by_aliases`, `search_by_origins`, + `search_by_magrefs`, `search_by_magazines`, and `search_by_issues` tables used for search scopes and magazine references. 3. Create a read‑only role/user (recommended). - Create user `zxdb_readonly`. @@ -48,9 +50,14 @@ pnpm dev ## Explorer UI overview - `/zxdb` — Search entries by title and filter by genre, language, and machine type; sort and paginate results. -- `/zxdb/entries/[id]` — Entry details with badges for genre/language/machine, and linked authors/publishers. -- `/zxdb/labels` and `/zxdb/labels/[id]` — Browse/search labels (people/companies) and view authored/published entries. +- `/zxdb/entries` — Entries search with scope toggles (titles/aliases/origins) and facets. +- `/zxdb/entries/[id]` — Entry details with related releases, downloads, origins, relations, and media. +- `/zxdb/releases` — Releases search + filters. +- `/zxdb/releases/[entryId]/[releaseSeq]` — Release detail: magazine references, downloads, scraps, and issue files. +- `/zxdb/labels` and `/zxdb/labels/[id]` — Browse/search labels (people/companies), permissions, licenses, and authored/published entries. - `/zxdb/genres`, `/zxdb/languages`, `/zxdb/machinetypes` — Category hubs with linked detail pages listing entries. +- `/zxdb/magazines` and `/zxdb/magazines/[id]` — Magazine list and issue navigation. +- `/zxdb/issues/[id]` — Issue detail with contents and references. Cross‑linking: All entities are permalinks using stable IDs. Navigation uses Next `Link` so pages are prefetched. @@ -67,6 +74,7 @@ All endpoints are under `/api/zxdb` and validate inputs with Zod. Responses are - `page`, `pageSize` — pagination (default pageSize=20, max=100) - `genreId`, `languageId`, `machinetypeId` — optional filters - `sort` — `title` or `id_desc` + - `scope` — `title`, `title_aliases`, or `title_aliases_origins` - `facets` — boolean; if truthy, includes facet counts for genres/languages/machines - Entry detail @@ -99,12 +107,13 @@ Runtime: API routes declare `export const runtime = "nodejs"` to support `mysql2 ## Troubleshooting - 400 from dynamic API routes: ensure you await `ctx.params` before Zod validation. +- Missing facets or scope toggles: ensure helper tables from `ZXDB_help_search.sql` exist. - Unknown column errors for lookup names: ZXDB tables use column `text` for names; Drizzle schema must select `text` as `name`. - Slow entry page: confirm server‑rendering is active and ISR is set; client components should not fetch on the first paint when initial props are provided. - MySQL auth or network errors: verify `ZXDB_URL` and that your user has read permissions. ## Roadmap -- Facet counts displayed in the `/zxdb` filter UI. -- Breadcrumbs and additional a11y polish. -- Media assets and download links per release (future). +- Issue-centric media grouping and richer magazine metadata. +- Additional cross-links for tags, relations, and permissions as UI expands. +- A11y polish and higher-level navigation enhancements. diff --git a/docs/getting-started.md b/docs/getting-started.md index e8d4fd9..c4abea1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -15,6 +15,12 @@ Run in development - Command: pnpm dev - Then open: http://localhost:4000 +ZXDB submodule local setup +- The ZXDB repo is a submodule used as a read-only reference for schemas/scripts. +- Some local SQL files are expected to exist but should stay untracked. +- Run: pnpm setup:zxdb-local + - This adds local excludes inside the submodule so `git status` stays clean. + Build and start (production) - Build: pnpm build - Start: pnpm start @@ -24,7 +30,9 @@ Lint - pnpm lint Deployment shortcuts -- Two scripts are available in package.json: +- Use pnpm deploy (or pnpm deploy:branch) to merge the current branch into `deploy` and push to explorer.specnext.dev. + - The deploy script refuses to run if there are uncommitted or untracked files. +- One-step push helpers (if you prefer manual branch selection): - pnpm deploy-test: push the current branch to test.explorer.specnext.dev - pnpm deploy-prod: push the current branch to explorer.specnext.dev -Ensure the corresponding Git remotes are configured locally before using these. + - Ensure the corresponding Git remotes are configured locally before using these. diff --git a/docs/index.md b/docs/index.md index c637fc6..30276bf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,5 +5,6 @@ Welcome to the Spectrum Next Explorer docs. This site provides an overview of th - Getting Started: ./getting-started.md - Architecture: ./architecture.md - Register Explorer: ./registers.md +- ZXDB Explorer: ./ZXDB.md If you’re browsing on GitHub, the main README also links to these documents. diff --git a/package.json b/package.json index 9319232..ecedbb9 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "lint": "eslint", "deploy": "bin/deploy.sh", "deploy:branch": "bin/deploy.sh", + "setup:zxdb-local": "bin/setup-zxdb-local.sh", "deploy-prod": "git push --set-upstream explorer.specnext.dev deploy", "deploy-test": "git push --set-upstream test.explorer.specnext.dev test" },