From 4192fc366e8615ecbc5b90d30a232a6687f6c4a7 Mon Sep 17 00:00:00 2001 From: Zsolt Tasnadi Date: Sun, 16 Aug 2026 11:07:39 +0200 Subject: [PATCH] Add the ttg-ops plugin: six skills for the forge estate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The marketplace held only MCP servers so far. These are skills for the work that keeps costing manual effort and quietly breaking: - ttg-publish-module — releasing a library, and verifying from a clean external project that the release is actually fetchable. Encodes the trap that cost the most: Gitea redirects old repo paths, but not Go module paths, so a repo can be reachable while `go get` fails. - ttg-move-repo — moving a repo and following it through every place that names it, including the ones redirects do not cover. - ttg-new-repo — creating one in the right org and registering it, so it cannot end up absent from the clone list the way batocera-store did. - ttg-ci-enroll — wiring a repo into the build, and the usual failure where the config exists but the repo was never registered. - ttg-audit-forge — the drift check between forge, clone list, wiki, catalog and CI. - ttg-update-docs — README, wiki page and the public site (Vue page plus both locale files) after a change. The rules stay in REPO_REFACT.md, WIKI_CONNECTION.md and ECOSYSTEM_PLAN.md; the skills read them instead of carrying a second copy that drifts. Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 9 +++ README.md | 25 +++++- plugins/ttg-ops/.claude-plugin/plugin.json | 10 +++ .../ttg-ops/skills/ttg-audit-forge/SKILL.md | 48 +++++++++++ plugins/ttg-ops/skills/ttg-ci-enroll/SKILL.md | 52 ++++++++++++ plugins/ttg-ops/skills/ttg-move-repo/SKILL.md | 63 +++++++++++++++ plugins/ttg-ops/skills/ttg-new-repo/SKILL.md | 71 ++++++++++++++++ .../skills/ttg-publish-module/SKILL.md | 49 ++++++++++++ .../ttg-ops/skills/ttg-update-docs/SKILL.md | 80 +++++++++++++++++++ 9 files changed, 405 insertions(+), 2 deletions(-) create mode 100644 plugins/ttg-ops/.claude-plugin/plugin.json create mode 100644 plugins/ttg-ops/skills/ttg-audit-forge/SKILL.md create mode 100644 plugins/ttg-ops/skills/ttg-ci-enroll/SKILL.md create mode 100644 plugins/ttg-ops/skills/ttg-move-repo/SKILL.md create mode 100644 plugins/ttg-ops/skills/ttg-new-repo/SKILL.md create mode 100644 plugins/ttg-ops/skills/ttg-publish-module/SKILL.md create mode 100644 plugins/ttg-ops/skills/ttg-update-docs/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index d77d359..7c0ab99 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -23,6 +23,15 @@ "author": { "name": "TTG" } + }, + { + "name": "ttg-ops", + "source": "./plugins/ttg-ops", + "description": "Skills for the TTG forge estate — publishing modules and gems, moving and creating repos, enrolling CI, auditing consistency, and updating the README, wiki and public site after a change.", + "version": "0.1.0", + "author": { + "name": "TTG" + } } ] } diff --git a/README.md b/README.md index f4fdbf3..3f362dc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # TTG Marketplace -Claude Code plugin marketplace with two plugins: +Claude Code plugin marketplace with three plugins: - **redmine-mcp** — dependency-free Node.js MCP server for the [Redmine REST API](https://www.redmine.org/projects/redmine/wiki/rest_api) - **grav-mcp** — dependency-free Node.js MCP server for the [Grav CMS REST API](https://learn.getgrav.org/20/api/endpoints) +- **ttg-ops** — skills for running the forge estate: releasing libraries, moving and creating repos, enrolling CI, auditing consistency, and updating the docs after a change ## Installation @@ -11,6 +12,7 @@ Claude Code plugin marketplace with two plugins: /plugin marketplace add /Users/tasi/Work/TTG/ttg-marketplace /plugin install redmine-mcp@ttg-marketplace /plugin install grav-mcp@ttg-marketplace +/plugin install ttg-ops@ttg-marketplace ``` (From a git repo: `/plugin marketplace add `.) @@ -63,9 +65,28 @@ Settings requested at install time: **Other:** `grav_scheduler` (jobs, status, history, run), `grav_dashboard` (stats, popularity, notifications), `grav_manage_webhooks`, flex objects: `grav_list_flex`, `grav_get_flex_object`, `grav_save_flex_object`, `grav_delete_flex_object` +## ttg-ops + +No settings — the skills drive the tools that are already on the machine: the +`tea` CLI (Gitea API, login `ttg`), `git`, `go` and `gem`. + +| Skill | What it does | +|---|---| +| `ttg-publish-module` | Releases a library: checks the module path against the repo's org, tags, and verifies from a clean external project that the release is fetchable. Knows that Gitea's redirect does **not** cover Go module paths or package namespaces. | +| `ttg-move-repo` | Moves or renames a repo and follows the change through: clone list, local remotes, wiki links and link text, `go.mod`, `Gemfile`, CI config, docs. | +| `ttg-new-repo` | Creates a repo in the right org and registers it everywhere — clone list, `WIKI_CONNECTION.md`, wiki page, CI. Includes the org/team setup a new org needs. | +| `ttg-ci-enroll` | Wires a repo into the Woodpecker build and proves it runs. Covers the usual failure: the config is there, the repo is not registered, nothing happens silently. | +| `ttg-audit-forge` | Audits drift between forge, clone list, wiki, catalog and CI. Reports first, fixes only on approval. | +| `ttg-update-docs` | After a change, updates the README of the repo that changed, its wiki page in `wiki-pages`, and the public site in `teletypegames` (Vue page plus **both** locale files). | + +The rules these skills follow are not duplicated inside them: the org taxonomy +lives in `REPO_REFACT.md`, the repo→wiki mapping in `devarea/WIKI_CONNECTION.md`, +and the ecosystem status in `ECOSYSTEM_PLAN.md`, all in the workspace root. The +skills read those rather than carry a second copy that drifts. + ## Notes -- Neither server has any npm dependencies (Node 18+ built-in `fetch`), and there is no build step. +- Neither MCP server has any npm dependencies (Node 18+ built-in `fetch`), and there is no build step. - Manual testing without the plugin: ```sh REDMINE_URL=https://redmine.example.com REDMINE_API_KEY=xxx \ diff --git a/plugins/ttg-ops/.claude-plugin/plugin.json b/plugins/ttg-ops/.claude-plugin/plugin.json new file mode 100644 index 0000000..a46debe --- /dev/null +++ b/plugins/ttg-ops/.claude-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "ttg-ops", + "displayName": "TTG Ops", + "version": "0.1.0", + "description": "Skills for the TTG forge estate: publishing modules and gems, moving repos between orgs, creating repos, enrolling CI, auditing consistency and updating the docs after a change.", + "author": { + "name": "TTG", + "email": "rastasi@gmail.com" + } +} diff --git a/plugins/ttg-ops/skills/ttg-audit-forge/SKILL.md b/plugins/ttg-ops/skills/ttg-audit-forge/SKILL.md new file mode 100644 index 0000000..7d4ae49 --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-audit-forge/SKILL.md @@ -0,0 +1,48 @@ +--- +name: ttg-audit-forge +description: Audit the TTG estate for drift between the forge, the clone list, the wiki, the catalog and CI — repos missing from the clone list, stale git URLs, repos with build config but no pipeline, catalog entries whose repo name differs, duplicate checkouts and leftover remotes. Reports findings; fixes only what the user approves. Use for a health check ("nézd át", "audit", "mi van elcsúszva", "konzisztencia"). +allowed-tools: Bash, Read, Grep, Glob +--- + +# ttg-audit-forge + +Konzisztencia-ellenőrzés a forge, a klónlista, a wiki, a katalógus és a CI között. **Először jelents, ne javíts** — a találatok egy része szándékos, és a felhasználónak kell eldöntenie. + +## Adatforrások + +| Mi | Honnan | +|---|---| +| repók | `tea api --login ttg "/user/repos?limit=50&page=N"` (lapozz) | +| orgok, csapatok | `tea api --login ttg /user/orgs`, `/orgs//teams` | +| csomagok | `tea api --login ttg "/packages/?limit=50"` | +| klónlista | `devarea/scripts/repos.list` + `check-repos.sh` | +| wiki-leképezés | `devarea/WIKI_CONNECTION.md` | +| katalógus | `https://teletypegames.org/api/software` | +| CI | `https://teletypegames.org/api/ci/pipelines` | + +## Ellenőrzések + +**1. Klónlista ↔ szerver.** `devarea/scripts/check-repos.sh`. MISSING = a szerveren van, a listán nincs; STALE = fordítva. A `repos.ignore`-ban lévők szándékosan kimaradnak. + +**2. Elavult git URL-ek.** A workspace-ben, a wikiben és a publikus oldalon: +```sh +grep -rn "git\.teletype\.hu" --exclude-dir=.git # legacy hoszt, sosem helyes +grep -rnoE "git\.teletypegames\.org(:[0-9]+)?/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+" +``` +Az orgot vesd össze a repo *mai* tulajdonosával. **Ne jelentsd hibának:** az `internal/-builder` és `internal/tic80pro` (csomagnévtér, nem költözik), az `api/packages/...` (registry-út), és a szándékos placeholderek (`games/example`). + +**3. Go modulnevek.** Minden `go.mod` első sora egyezzen a repo mai `/` útjával. A Gitea átirányítása **nem fedi** a modulneveket, tehát az eltérés valódi törés. Nézd a fogyasztók `require`/`replace` sorait is: a `replace ... => ../` CI-ben mindig bukik. + +**4. Gem- és csomaghivatkozások.** `Gemfile`, `Gemfile.lock`, `*.gemspec` — hoszt és org. A gemspec `allowed_push_host`-ja egyezzen a publikáló pipeline `--host` értékével. + +**5. CI-lefedettség.** Vesd össze háromfelé: van-e `.woodpecker.yaml` **vagy** `.woodpecker.yml`, szerepel-e a repo a `/api/ci/pipelines`-ban, és van-e katalógus-bejegyzése. A tipikus hiba: konfig megvan, regisztráció nincs — ilyenkor a build csendben nem fut. Nézd a `last_pipeline_status` mezőt is. + +**6. Katalógus ↔ repo.** A katalógus szoftverneve és a repo neve eltérhet (`bevydemo` vs `bevy-demo`). Ez önmagában nem hiba, de a wikiben és az oldalon linkként **elszáll**, ha a szoftvernevet használják repo-útként. + +**7. Org-higiénia.** Minden orgnak legyen megjelenítendő neve és `Teletypers` csapata a `games` mintájára (azonos `units_map`, `includes_all_repositories`, tagok). Üres orgnál nézd meg a csomagjait, mielőtt bárki törölné. + +**8. Workspace-higiénia.** Duplikált checkout (ugyanaz a repo két mappában, eltérő állapotban), `origin`-on kívüli elfekvő remote, és olyan branch, aminek az upstreamje nem `origin/...` — ebből egy sima `git push` rossz helyre megy. + +## Jelentés + +Csoportosítsd a találatokat aszerint, hogy **valódi törés**, **elcsúszás** vagy **szándékos**. Minden találathoz add meg a fájlt és a sort. A javításra kérj jóváhagyást; ha a felhasználó kéri, a repo-mozgatáshoz a `ttg-move-repo`, a dokumentációhoz a `ttg-update-docs` skill való. diff --git a/plugins/ttg-ops/skills/ttg-ci-enroll/SKILL.md b/plugins/ttg-ops/skills/ttg-ci-enroll/SKILL.md new file mode 100644 index 0000000..daf9338 --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-ci-enroll/SKILL.md @@ -0,0 +1,52 @@ +--- +name: ttg-ci-enroll +description: Wire a TTG repo into the Woodpecker build and prove the pipeline actually runs — the one-line platform config, the builder image, registration, and the catalog entry it publishes to. Use when a repo should start building, or when a build is not running even though the config is in place ("kösd be a CI-be", "nem fut a build", "enroll CI"). +allowed-tools: Bash, Read, Edit, Write, Grep, Glob +--- + +# ttg-ci-enroll + +Egy repo bekötése a buildbe. A leggyakoribb hiba nem a konfig hiánya, hanem hogy **a konfig megvan, de a repo nincs regisztrálva** — ilyenkor semmi nem történik, és nincs hibaüzenet sem. + +## Hogyan épül fel a build + +A repo `.woodpecker.yaml`-ja egyetlen sor: + +```yaml +# The CI pipeline is served by the update server: GET /build/config?platform=ebitengine +platform: ebitengine +``` + +A tényleges pipeline-t a WarpEngine **config-extension** szolgáltatása állítja elő (`/build/config`), a builder image-eket pedig a `services/teletypegames` `apps/api/config/initializers/warp_engine.rb`-je sorolja fel (`c.ci_platforms`). Ezért egy image-bump egyetlen sor ott, nem hét repóban. + +Támogatott platformok: `c64`, `tic80`, `ebitengine`, `love`, `godot`, `bevy`, `phaser`. + +## Lépések + +1. **Platform-konfig.** Ha nincs, hozd létre a `.woodpecker.yaml`-t a fenti egy sorral. **Figyelj a kiterjesztésre:** mindkettő él a vadonban (`.woodpecker.yaml` és `.woodpecker.yml`), keresd mindkettőt, mielőtt hiányzónak nyilvánítod. Új repóhoz a `.yaml` a preferált. + +2. **Toolchain.** A platform `build/-tools` repója adja a Makefile-mintát (`example-makefile.make`) és a builder image Dockerfile-ját. Új projekt Makefile-ja innen induljon, ne másolásból. + +3. **Go projekt esetén `GOPRIVATE`.** Ha a repo saját modulra (`engines/…`) támaszkodik, a Makefile-ban legyen `export GOPRIVATE = git.teletypegames.org` — a saját modulјaink nincsenek a proxy.golang.org-on. Ha `replace ... => ../` direktíva van a `go.mod`-ban, **az CI-ben biztosan bukik** (testvérkönyvtárat vár): adasd ki a függőséget rendes verzióval a `ttg-publish-module` skillel, és dobd el a replace-t. + +4. **Regisztráció a Woodpeckerben.** A repo aktiválása a Woodpecker felületén történik; a WarpEngine oldali nyilvántartás ebből szinkronizálódik. + +5. **Ellenőrzés.** Mit tud a rendszer: + ```sh + curl -s https://teletypegames.org/api/ci/pipelines + ``` + A sorokban `repo_owner`, `repo_name`, `platform`, `active`, `last_pipeline_status`. Amíg a repo nincs a listában, nem fut rá build. + +## Ha „be van kötve", mégsem fut + +Ellenőrizendő sorrendben: + +- **Tényleg a listában van?** A `/api/ci/pipelines` a mérce, nem a repóban lévő fájl. +- **Elavult tulajdonos.** A tábla `repo_owner`-je org-váltás után a régi orgot mutathatja, amíg a szinkron nem futott. A szinkron `woodpecker_repo_id`-ra kulcsol és a távoli adatból frissíti a tulajdonost, tehát magától rendbe jön — de addig félrevezet. +- **Tag-esemény.** Ha a pipeline `when: event: tag`-re van kötve (publikáló lépések), a sima push nem indítja. Nézd meg, hogy a repón engedélyezett-e a tag-build. +- **Secret jogok.** A publikáló lépések tokenjének `package:write` kell, és org-váltás után a leírásában szereplő cél is elavulhat. +- **`last_pipeline_status`.** A `failure`/`error` érték már önmagában irány — ne a konfigot kezdd el javítgatni, előbb nézd meg, mi bukott. + +## A végén + +Ha a bekötés új platformot tesz élővé, az `ECOSYSTEM_PLAN.md` platform-lefedettségi táblázatában javítsd az „Aktív CI" oszlopot. diff --git a/plugins/ttg-ops/skills/ttg-move-repo/SKILL.md b/plugins/ttg-ops/skills/ttg-move-repo/SKILL.md new file mode 100644 index 0000000..44218fc --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-move-repo/SKILL.md @@ -0,0 +1,63 @@ +--- +name: ttg-move-repo +description: Move or rename a repo on the TTG forge and follow the change through everywhere it is referenced — clone list, local remotes, wiki links, Go module paths, Gemfiles, CI config and the docs. Knows what Gitea's redirect covers and what it silently does not. Use when a repo changes org or name ("tedd át a X orgba", "nevezd át", "move repo", "rename repo"). +allowed-tools: Bash, Read, Edit, Write, Grep, Glob +--- + +# ttg-move-repo + +Egy repo áthelyezése vagy átnevezése a forge-on, és — ami a munka nagyobbik fele — az utókövetés. + +## Mit fed az átirányítás és mit nem + +A Gitea az átnevezés/áthelyezés után is kiszolgálja a régi `owner/repo` utat (`repo_redirect`), ugyanarra a SHA-ra. **Ezért túléli:** a meglévő klónok `pull`/`push`-a, a wiki szövegbeli linkjei, a `repos.list` régi URL-jei, a HTTPS böngészőlinkek (301). + +**Amit nem fed — ezeket kézzel kell:** + +| Mi | Hol keresd | +|---|---| +| Go modulnév | `go.mod` első sora + minden belső import + a fogyasztók `require`/`replace` sorai | +| Konténer-csomag útvonalak | `git.teletypegames.org/internal/` — a csomagnévtér nem költözik a repóval | +| Gem registry névtér | `api/packages//rubygems` a gemspecben és a pipeline-ban | +| CI push URL | a mirror/publikáló pipeline `git push` sora | +| Woodpecker repo-kötés | az új tulajdonos alatt újra kell regisztrálni | + +## Lépések + +1. **Cél eldöntése.** Az org a repo *rendeltetését* jelöli, nem a titkosságát (azt a repo `private` kapcsolója). A besorolási szabályok és a mai kiosztás a workspace gyökér `REPO_REFACT.md`-jében. Ha a besorolás nem egyértelmű, kérdezz, ne tippelj. + +2. **Áthelyezés.** + ```sh + tea api --login ttg -X POST -d '{"new_owner":""}' /repos///transfer + ``` + Átnevezéshez `-X PATCH -d '{"name":"<új-név>"}' /repos//`. + Ha a cél org még nincs: `tea api --login ttg -X POST -d '{"username":"","visibility":"public"}' /orgs` — és **utána add meg neki a nevet és a `Teletypers` csapatot** a `games` mintájára (lásd `ttg-new-repo`). + +3. **Átirányítás ellenőrzése**, mielőtt bármi másba kezdesz: + ```sh + git ls-remote ssh://git@git.teletypegames.org:2222// HEAD + git ls-remote ssh://git@git.teletypegames.org:2222/<új>/ HEAD + ``` + Azonos SHA = működik. + +4. **`devarea/scripts/repos.list`** — írd át az érintett sor URL-jét, majd `devarea/scripts/check-repos.sh`. A szkript org-agnosztikus (`tea repo list`-ből olvas `owner/name`-et), nem kell hozzányúlni. Zöld futás = a lista és a szerver fedik egymást. + +5. **Lokális remote-ok.** A workspace-checkoutok `origin`-ja a régi URL-en marad. Állítsd át `git remote set-url origin <új URL>`. Söpörd végig a többi repót is elfekvő remote-ért (`git remote` ≠ csak `origin`, vagy az upstream nem `origin/...`) — volt már régi hosztra mutató alias, amire egy sima `git push` ment volna. + +6. **Hivatkozások.** Keress a `wiki-pages` és a `teletypegames` repóban, meg a workspace többi részében: + ```sh + grep -rn "/" --exclude-dir=.git + ``` + Ne feledd a **linkszövegeket** sem (`` `internal/wiki-pages` ``), ne csak az URL-eket. Óvatosan az általános szabályokkal: a `bbs/session.rb` alakú backtickes hivatkozások forrásfájlok, nem org-utak. + +7. **Dokumentáció.** Futtasd a `ttg-update-docs` skillt — az intézi a README-t, a wikit és a publikus oldalt. A `devarea/WIKI_CONNECTION.md` `Org` oszlopát is frissíteni kell. + +8. **Ellenőrzés.** Az átírt URL-eket kérd le élesben (HTTP HEAD). A 404 nem mindig hiba: privát repo névtelenül 404, és a placeholder URL-ek (`games/example`) szándékosak. + +## Ha org szűnne meg + +Mielőtt kiürült orgot törölnél, **nézd meg a csomagjait**: +```sh +tea api --login ttg "/packages/?limit=50" +``` +Az `internal` org nulla repóval is él, mert nyolc builder image-et tart — a törlése minden buildet megölne. diff --git a/plugins/ttg-ops/skills/ttg-new-repo/SKILL.md b/plugins/ttg-ops/skills/ttg-new-repo/SKILL.md new file mode 100644 index 0000000..66e5271 --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-new-repo/SKILL.md @@ -0,0 +1,71 @@ +--- +name: ttg-new-repo +description: Create a repo on the TTG forge in the right org and register it everywhere it has to appear — clone list, wiki page, WIKI_CONNECTION table, and CI if it builds something. Use when the user wants a new repository, project or tool ("új repo", "create repo", "kezdjünk egy új projektet"). +allowed-tools: Bash, Read, Edit, Write, Grep, Glob +--- + +# ttg-new-repo + +Új repo létrehozása úgy, hogy ne maradjon árván. A tapasztalat szerint a repo elkészül, a nyilvántartásból meg kimarad — ez a skill ezt előzi meg. + +## 1. Melyik org + +Az org a repo **rendeltetését** jelöli; a titkosságot a repo `private` kapcsolója adja, nem az org. A mai kiosztás és az egymondatos definíciók a workspace gyökér `REPO_REFACT.md`-jében vannak. Röviden: + +| Org | Mi kerül bele | +|---|---| +| `games` | katalógus-termék, amivel valaki játszik | +| `demos` | platformbemutató (katalógus-státusz `demo`) | +| `engines` | újrafelhasználható motor/könyvtár, amitől más repók függnek | +| `bbs` | BBS szerverek és showcase-ek | +| `build` | CI toolchain és builder image | +| `services` | ami a mi szerverünkön fut | +| `tools` | amit egy ember telepít és futtat magának | +| `infra` | maga a kiszolgáló-környezet | + +Ha a besorolás vitatható, **kérdezd meg a felhasználót** — a rossz org később org-váltást és utókövetést jelent. + +## 2. Létrehozás + +```sh +tea api --login ttg -X POST -d '{"name":"","private":false,"auto_init":false}' /orgs//repos +``` + +A `private` a tartalom érzékenységéről szóljon, ne az orgról. + +## 3. Nyilvántartásba vétel + +- **`devarea/scripts/repos.list`** — új sor `|ssh://git@git.teletypegames.org:2222//` alakban, ábécérendben a blokkján belül. A workspace-mappa és az org **szándékosan nem azonos**: a mappák aszerint csoportosítanak, hogyan dolgozol rajtuk, az orgok aszerint, mi a repo. +- **`devarea/scripts/check-repos.sh`** — futtasd. Ha zöld, a lista fedi a szervert. Ez a lépés fogja el a „elkészült, de sehol nincs nyilvántartva" hibát. +- **`devarea/WIKI_CONNECTION.md`** — ha lesz wiki-oldala, új sor a táblázatba (`Folder`, `Org`, `Title`, `Wiki file`, `URL`). Ha nem lesz, vedd fel a „Folders without a wiki page" felsorolásba. + +## 4. Wiki-oldal + +Ha a repo dokumentálást érdemel, hozz létre `wiki-pages/pages///default.md`-t. Szekció-választás a rendeltetés szerint: `development/` platformok, `infrastructure/` kiszolgáló, `others/` eszközök, `projects/` termékek. + +A frontmatter kötelező mezői: `title`, `visible`, `id`, `description`, `date`, `locale`, `repo`, `taxonomy.tag`. **Az `id` legyen egyedi** — ellenőrizd (`grep -rh "^id:" pages/ | sort | uniq -d`), a legnagyobb használt fölött adj újat. A `config/sitenav.yaml`-ba is kerüljön bejegyzés, ha a menüben a helye. + +## 5. CI + +Ha a repo buildel valamit, futtasd a `ttg-ci-enroll` skillt. + +## 6. Kezdő tartalom + +Legyen `README.md` az első committól. Ha a repo egy meglévő minta rokona (pl. új `*-tools` vagy új store), nézd meg a testvért, és kövesd a szerkezetét — ne találj ki újat. + +## Ha új orgot kell létrehozni + +Nem elég a puszta org: adj neki **megjelenítendő nevet és `Teletypers` csapatot** a `games` mintájára, különben kilóg a sorból. + +```sh +tea api --login ttg -X POST -d '{"username":"","visibility":"public"}' /orgs +tea api --login ttg -X PATCH -d '{"full_name":"Teletype Games ","description":""}' /orgs/ +``` + +A csapat konfigurációját **ne gépeld be** — olvasd ki a mintából és másold: +```sh +tea api --login ttg /orgs/games/teams # a Teletypers csapat units_map-je és beállításai +tea api --login ttg /teams//members # a tagok +tea api --login ttg -X POST -d '' /orgs//teams +tea api --login ttg -X PUT /teams/<új-id>/members/ +``` diff --git a/plugins/ttg-ops/skills/ttg-publish-module/SKILL.md b/plugins/ttg-ops/skills/ttg-publish-module/SKILL.md new file mode 100644 index 0000000..2351e89 --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-publish-module/SKILL.md @@ -0,0 +1,49 @@ +--- +name: ttg-publish-module +description: Release a TTG library as a consumable package — a Go module tag or a RubyGems push to the forge registry. Checks the module path against the repo's org, tags the version, and verifies from a clean external project that the release is actually fetchable. Use when the user wants to publish, release, tag or version a library ("adjuk ki", "publikáld", "release", "tag a version"). +allowed-tools: Bash, Read, Edit, Grep, Glob +--- + +# ttg-publish-module + +Egy TTG könyvtár kiadása úgy, hogy utána **tényleg le lehessen hívni**. A skill nem ér véget a tagnél: külső projektből visszaellenőrzi. + +## Amit tudni kell előre + +- A forge `https://git.teletypegames.org`. A régi `git.teletype.hu` hosztot soha ne használd. +- A Gitea átirányítja a régi `owner/repo` utakat egy átnevezés vagy org-váltás után — **de ez nem terjed ki a Go modulnevekre és a csomag-névterekre.** Ez a leggyakoribb hiba: a repo elérhető, a `go get` mégis elszáll. +- A könyvtárak az `engines` orgban laknak. Az org-szabályok a workspace gyökér `REPO_REFACT.md`-jében vannak. + +## Go modul + +A Go-nál **nincs csomagtár**: a repo maga a terjesztés, a git tag a verzió. + +1. **Modulnév ellenőrzése.** A `go.mod` első sora legyen `git.teletypegames.org//`, ahol az org és a repo a *mai* helye. Ha eltér, írd át, és vele együtt minden belső importot (`grep -rl '"' --include="*.go"`). Két valós eset volt: `module game` (semmilyen néven nem hivatkozható) és egy org-váltást nem követő útvonal. +2. **Fordul-e.** `go build ./...` és `go vet ./...`. Ha a repo ebiten-t használ, macOS-en cgo-figyelmeztetések jönnek az upstreamből — azok nem a mi hibánk, szűrd ki őket. +3. **Fogyasztók.** Keresd meg, ki hivatkozik rá (`grep -rn '' --include=go.mod` a workspace-ben). Ha van `replace ... => ../` direktíva, **az kiadás után elhagyható** — és el is kell hagyni, mert testvérkönyvtárat vár, ami CI-checkoutban nincs, tehát bukó pipeline-t okoz. +4. **Verzió.** Ha nincs korábbi tag, `v0.1.0` az őszinte kezdés. Egyébként semver a változás mértéke szerint. A tag legyen annotált: `git tag -a v0.1.0 -m " v0.1.0 — "`. +5. **Push.** `git push origin master && git push origin v0.1.0`. +6. **Ellenőrzés — ezt ne hagyd ki.** Üres könyvtárban: + ```sh + go mod init tmp/probe + GOPRIVATE=git.teletypegames.org GOPROXY=direct GOSUMDB=off \ + go get git.teletypegames.org//@v0.1.0 + ``` + Ha ez lefut és a `go.mod`-ba bekerül a verzió, a kiadás valódi. + +**`GOPRIVATE`.** A saját modulјaink nincsenek a proxy.golang.org-on és a publikus checksum adatbázisban, ezért minden fogyasztónak kell `GOPRIVATE=git.teletypegames.org`. Ha a fogyasztó egy TTG repo, tedd a Makefile-jába (`export GOPRIVATE = git.teletypegames.org`), ne csak a környezetbe — így CI-ben is működik. + +## Ruby gem + +1. **Hol fejlesztik.** Ha a gem egy monorepo alkönyvtárában él (a `warp_engine` a `services/teletypegames` `libs/ruby/warp_engine`-jében), a gemspecet **ott** módosítsd, ne a split mirrorban — a mirror csak publikálásra való, a CI felülírja. +2. **`allowed_push_host`.** Pontosan egyezzen a `gem push --host` értékével. A forge orgonként külön registryt szolgál ki: + `https://git.teletypegames.org/api/packages//rubygems` + Ha csak a hosztnév van benne, a push visszautasításra kerül. +3. **Van-e már pipeline.** Nézd meg a repo `.woodpecker.yaml`-ját: lehet, hogy a publikálás már meg van írva és csak sosem futott. Ilyenkor **ne kézzel pusholj** — javítsd a pipeline-t (org-hivatkozások!) és tedd ki a tagot, amire figyel (a `warp_engine`-nél `warp_engine-v*`, nem `v*`). +4. **Ellenőrzés.** `tea api --login ttg "/packages/?limit=20"`. Ha üres marad, a Woodpecker naplója kell: indít-e buildet a tag-esemény, és van-e a CI tokennek `package:write` joga. + +**Korlát:** a `tea api` csak JSON törzset küld, bináris feltöltésre nem alkalmas — kézi `gem push`-hoz nyers token kell, amit a `tea` titkosítva tárol, tehát a felhasználónak kell megadnia. + +## A végén + +Foglald össze, mi hol jelent meg: a Go modulnál a **repo tagje** a kiadás helye (a csomag-registry üres marad, és ez így helyes), a gemnél az **org rubygems registryje**. Ha az `ECOSYSTEM_PLAN.md` említi a csomagot, frissítsd a státuszát. diff --git a/plugins/ttg-ops/skills/ttg-update-docs/SKILL.md b/plugins/ttg-ops/skills/ttg-update-docs/SKILL.md new file mode 100644 index 0000000..29391e1 --- /dev/null +++ b/plugins/ttg-ops/skills/ttg-update-docs/SKILL.md @@ -0,0 +1,80 @@ +--- +name: ttg-update-docs +description: After a change has been made, update every place that documents it — the README of the repo that changed, the wiki page in wiki-pages, and the public site in teletypegames (Vue page plus both locale files). Finds the affected documents from the actual diff rather than guessing. Use after finishing a change ("frissítsd a doksit", "update docs", "vezesd át a dokumentációba"). +allowed-tools: Bash, Read, Edit, Write, Grep, Glob +--- + +# ttg-update-docs + +Egy elvégzett módosítás átvezetése a dokumentációba. Három célpont van, és **nem mindig mind a három érintett** — a skill első fele annak a kiderítése, melyik. + +## 1. Mi változott + +Ne emlékezetből dolgozz. Nézd meg a tényleges diffet: + +```sh +git -C status --short +git -C diff --stat HEAD +git -C log --oneline -10 +``` + +Ha több repót érintett a munka, mindegyikre. Írd össze konkrétan: **mi lett más a felhasználó szemszögéből** — új parancs, megváltozott útvonal, új konfigkulcs, átnevezett dolog, megszűnt lépés. Ami csak belső refaktor, azt ne dokumentáld. + +## 2. README — abban a repóban, ahol a változás történt + +A legközelebbi és leggyakrabban elfelejtett célpont. Nézd át: + +- Telepítési és használati parancsok — ha útvonal vagy parancsnév változott, itt is változik. +- Konfigurációs táblázatok — új vagy átnevezett kulcs. +- Könyvtárszerkezet-ábrák. +- Repo-URL-ek, ha a repo költözött. + +Ha a változás egy **mintát** érint, ami több repóban ismétlődik (pl. egy `build/*-tools` sablon vagy egy store-minta), nézd meg a testvéreket is — a minta és a példány ne csússzon szét. + +## 3. Wiki — a `wiki-pages` repo + +A wiki **Grav CMS**, a tartalom `wiki-pages/pages/<útvonal>/default.md`. Az oldal nem CMS-ben, hanem fájlban él, tehát szerkeszthető. + +**Melyik oldal tartozik a repóhoz:** a `devarea/WIKI_CONNECTION.md` táblázata mondja meg (`Folder` → `Wiki file`). Ha nincs benne, vagy `grep -rl "" wiki-pages/pages/`. + +Amire figyelj: + +- **Frontmatter.** A `repo:` mező URL-je is elavulhat. Az `id` egyedi legyen (`grep -rh "^id:" pages/ | sort | uniq -d`). +- **Mindkét irány.** Ha egy oldal átnevezésre vagy kettévágásra kerül, a `config/sitenav.yaml` bejegyzését is vezesd át, és a **másik két célpontban** lévő wiki-linkeket is (a publikus oldal `CONFIG.wikiBase`-re épülő URL-jét is beleértve). +- **Nem csak `pages/`.** A `wiki-pages` repóban van `README.md`, `bbs/` (Gemfile is!), `fetcher/` — ezekben is lehet érintett hivatkozás. +- **Commit-konvenció.** A `wiki-pages` repónak saját `git-commit` skillje van, és a konvenciója szerint **nem kerül trailer az üzenetbe** (se `Co-Authored-By`, se generált aláírás). Kövesd. + +## 4. Publikus oldal — a `teletypegames` repo + +A publikus oldal **Vue 3 SPA**, nem CMS. A tartalom három helyen van, és **mindhármat együtt kell módosítani**: + +| Mi | Hol | +|---|---| +| oldalszerkezet, linkek, kódrészletek | `apps/frontend/src/page//Page.vue` | +| minden megjelenő szöveg | `apps/frontend/src/i18n/locales/en.ts` **és** `hu.ts` | +| útvonal | `apps/frontend/src/router/.router.ts` | + +**A szövegek nem a `.vue`-ban vannak**, hanem a locale fájlokban, `t('szekció.kulcs')` hivatkozással. Új szöveghez új kulcs kell **mindkét nyelvben**, azonos szerkezetben. Az `en` a fallback. + +Ami tipikusan a `.vue`-ban marad hardkódolva, és ezért elavul: repo-URL-ek, telepítő egysorosok, CLI-részletek, külső linkek. + +**Ellenőrzés — ezt ne hagyd ki:** +```sh +cd apps/frontend +npm run build # vue-tsc típusellenőrzés + vite build +npm run lint +npm test +``` +A lintben és a tesztekben lehetnek korábbról meglévő figyelmeztetések/hibák; ha ilyet látsz, `git stash`-sel ellenőrizd, hogy a te változtatásod okozta-e, és mondd meg a felhasználónak, melyik volt már ott. + +## 5. Ami a három célponton kívül esik + +Ha a változás a repo-állományt vagy az ökoszisztéma állapotát érinti, ezek is naplót kérnek: + +- `devarea/scripts/repos.list` és `devarea/WIKI_CONNECTION.md` — új, átnevezett vagy áthelyezett repo. +- Workspace gyökér `REPO_REFACT.md` — org-struktúra változás. +- Workspace gyökér `ECOSYSTEM_PLAN.md` — ha egy hiányosság megszűnt vagy egy javasolt lépés elkészült, a státuszát vezesd át. + +## 6. Zárás + +Repónként külön commit, mindegyik a saját konvenciója szerint. A végén foglald össze a felhasználónak **repónként**, mi változott és mi maradt szándékosan érintetlenül — és ha valamit nem tudtál ellenőrizni (pl. böngészőben renderelni), azt mondd ki, ne hallgasd el.