From a55f207f80b576bd21eebf72aa278f3c365ac6f3 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sun, 24 May 2026 18:22:16 -0700 Subject: [PATCH] docs(devops): add executable roadmap with checklist for Codex agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds HOSTINGER_GITEA_RUNNER_ROADMAP.md β€” a single execution tracker that Codex on the Hostinger VM works through phase-by-phase, ticking checkboxes and recording commit hashes as it goes. Structure: - 6 phases (P0 Pre-flight β†’ P5 First real release) + P6 review handoff - Each task: [ ] checkbox + Commit hash field + Status note - Detail steps live in the two companion docs (act_runner setup + publish workflow); the roadmap is the orchestrator - Final report section Codex fills in when P0-P5 are complete - Human review checklist (R1-R9) for verification after handoff - Operating notes: commit message format, when to ask, never-do list - Change log table Codex auto-appends to Critical invariant repeated at P3.6 and P5.4: cross-Gitea SHA1 comparison must match. If it doesn't, Codex stops β€” it's the load-bearing architectural guarantee that the dual-Gitea, no-sync- script model rests on. Also adds roadmap-pointer banners to the two companion docs (HOSTINGER_GITEA_ACT_RUNNER_SETUP.md, GITEA_PACKAGES_PUBLISH_WORKFLOW.md) so anyone landing there knows the master tracker exists. --- .../devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md | 7 +- .../HOSTINGER_GITEA_ACT_RUNNER_SETUP.md | 3 + docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md | 278 ++++++++++++++++++ 3 files changed, 287 insertions(+), 1 deletion(-) create mode 100644 docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md diff --git a/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md b/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md index 0ae51752..b4946dfb 100644 --- a/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md +++ b/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md @@ -1,9 +1,14 @@ # `@bytelyst/*` Package Publish Workflow (Gitea Actions) +> πŸ“‹ **Track progress in the master roadmap:** [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) β€” Phase 4 references this doc. Codex updates the roadmap checkboxes as each step here completes. + > **Delegation prompt for a coding agent.** > Implements the canonical `publish-packages.yml` workflow that publishes `@bytelyst/*` packages to the Gitea npm registry on every `v*` tag, and propagates it to all 20+ ByteLyst repos. -> Companion: [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md) β€” the runner that executes this workflow. +> Companions: +> +> - [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) β€” execution tracker. +> - [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md) β€” the runner that executes this workflow. --- diff --git a/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md b/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md index 5dfc879d..53d19387 100644 --- a/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md +++ b/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md @@ -1,10 +1,13 @@ # Hostinger VM β€” Gitea Actions `act_runner` Setup +> πŸ“‹ **Track progress in the master roadmap:** [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md). The roadmap has the checklist; this doc has the implementation detail. Codex updates checkboxes + commit hashes in the roadmap as each phase completes. + > **Delegation prompt for the Codex agent running on the Hostinger VM.** > Canonical CI runner setup for the ByteLyst ecosystem. Read top-to-bottom before executing. Stop and ask the human if any pre-flight check fails or any deliverable is unclear. > Companion docs: > +> - [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) β€” **execution tracker (this doc's checklist)**. > - [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) β€” the publish workflow this runner executes. > - [`HOSTINGER_GITHUB_RUNNER_SETUP.md`](./HOSTINGER_GITHUB_RUNNER_SETUP.md) β€” Plan B (GitHub Actions runner). Kept for reference. diff --git a/docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md b/docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md new file mode 100644 index 00000000..2867ffe7 --- /dev/null +++ b/docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md @@ -0,0 +1,278 @@ +# Hostinger Gitea Actions Runner β€” Execution Roadmap + +> **Codex agent β€” this is your execution tracker.** +> +> 1. Read this file top-to-bottom before starting. +> 2. Work through phases in order. **Do not skip phases.** +> 3. After completing each task, edit this file: change `- [ ]` β†’ `- [x]`, fill in the commit hash, and add a one-line status note. Then commit the roadmap update with message `chore(roadmap): mark P. complete`. +> 4. If anything blocks you or surprises you, stop, fill in the `Status` line as `BLOCKED: `, and report back to the human. +> 5. When all phases are βœ…, fill in **Β§Review handoff** and ping the human. +> +> **Detailed instructions** for each phase live in two companion docs β€” link from each phase. Don't repeat the details here; just track progress. +> +> - Runner install detail: [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md) +> - Publish workflow detail: [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) +> - Plan B (GitHub Actions instead, not used): [`HOSTINGER_GITHUB_RUNNER_SETUP.md`](./HOSTINGER_GITHUB_RUNNER_SETUP.md) + +--- + +## 🎯 Outcome + +After this roadmap is fully executed, the following invariant holds: + +> Pushing a `v*` tag to both Gitea instances (`git push origin && git push gitea --tags`) causes each Gitea's `act_runner` to independently build `@bytelyst/*` packages from the same git tag and publish byte-identical tarballs to its local Gitea registry β€” **with no sync script and no manual intervention**. + +The cross-Gitea SHA comparison in P3.6 and P5.3 is the proof. + +--- + +## πŸ“‹ Master execution tracker + +Total phases: **6** (P0 β†’ P5) + **Review handoff (P6)** + +### P0 β€” Pre-flight + environment verification + +> Detail: [Β§2 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#2-pre-flight-checks-run-first-do-not-skip) + +- [ ] **P0.1** All 10 pre-flight checks pass on Hostinger VM + - Commit: _none (read-only)_ + - Status: `` +- [ ] **P0.2** Architecture confirmed and `RUNNER_ARCH` exported + - Commit: _none_ + - Status: `` +- [ ] **P0.3** Human confirmed registration scope (instance-level recommended) + - Commit: _none_ + - Status: `` +- [ ] **P0.4** Human confirmed E2E throwaway-package consent + - Commit: _none_ + - Status: `` + +### P1 β€” Install `act_runner` on Hostinger VM + +> Detail: [Β§4 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#4-installation) + +- [ ] **P1.1** Create `gitea-runner` user (idempotent; docker group) + - Commit: _system change, not git_ + - Status: `` +- [ ] **P1.2** Download `act_runner` binary, SHA256-verify, install to `/usr/local/bin/` + - Commit: _system change_ + - Status: `` +- [ ] **P1.3** Obtain registration token from Gitea (instance level) + - Commit: _none (token in memory only)_ + - Status: `` +- [ ] **P1.4** Register runner with config.yaml (Docker mode, `node:20-bookworm` label mapping) + - Commit: _system change_ + - Status: `` +- [ ] **P1.5** Mount `~/.gitea_npm_token` to `gitea-runner` (mode 600) + - Commit: _system change_ + - Status: `, owner gitea-runner:gitea-runner, mode 600, bytes=...>` +- [ ] **P1.6** Install systemd service `gitea-act-runner.service` and verify `active (running)` + "Polling" in journal + - Commit: _system change_ + - Status: `` +- [ ] **P1.7** Confirm runner shows "Idle" green in Gitea Admin UI (`/-/admin/actions/runners`) + - Commit: _none (UI verification)_ + - Status: `">` + +### P2 β€” Smoke test (runner picks up jobs) + +> Detail: [Β§5 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#5-smoke-test-basic--runner-picks-up-jobs) + +- [ ] **P2.1** Create branch `runner/gitea-smoke` with `.gitea/workflows/runner-smoke.yml` + - Commit: `` + - Status: `` +- [ ] **P2.2** Trigger smoke workflow via Gitea Actions UI + - Commit: _trigger only_ + - Status: `` +- [ ] **P2.3** All smoke steps pass (host info, Node, pnpm, Gitea reachability, token presence) + - Commit: _none_ + - Status: `` + +### P3 β€” End-to-end validation (throwaway package + cross-Gitea byte-identical check) + +> Detail: [Β§6 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#6-end-to-end-validation--proves-the-actual-publish-pipeline) + +- [ ] **P3.1** Create throwaway `@bytelyst/_runner-e2e-test` package on branch `runner/gitea-e2e` + - Commit: `` + - Status: `` +- [ ] **P3.2** Add `.gitea/workflows/runner-e2e-publish.yml` to the same branch + - Commit: `` + - Status: `` +- [ ] **P3.3** Trigger E2E workflow with `version=0.0.1-e2e.1` + - Commit: _trigger only_ + - Status: `` +- [ ] **P3.4** Verify publish succeeds + Gitea registry returns the version + - Commit: _none_ + - Status: `` +- [ ] **P3.5** Verify consumer `pnpm install` + `require()` works from clean `/tmp` dir + - Commit: _none_ + - Status: `` +- [ ] **P3.6** **Cross-Gitea SHA1 comparison** β€” corp Mac runner publishes same version to corp Gitea; verify tarball shasum matches Hostinger + - Commit: _none (cross-machine verification)_ + - Status: `` + - **This is the architectural invariant. If it fails, STOP and investigate Node/pnpm/lockfile version drift before proceeding to P4.** +- [ ] **P3.7** Cleanup: delete test version from both Giteas, delete `runner/gitea-e2e` branch, remove `packages/_runner-e2e-test/` + - Commit: `` (the cleanup commit on main) + - Status: `` + +### P4 β€” Implement publish-packages.yml (the real workflow) + +> Detail: [Publish workflow doc](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) + +- [ ] **P4.1** Look up current `node:20-bookworm` digest from Docker Hub via `docker inspect` on Hostinger + - Commit: _none_ + - Status: `` +- [ ] **P4.2** Create `.gitea/workflows/publish-packages.yml` in `learning_ai_common_plat` with the digest pinned (replace `PIN_THIS_DIGEST_FOR_DETERMINISM`) + - Commit: `` + - Status: `` +- [ ] **P4.3** Confirm `GITEA_NPM_TOKEN` is set as a Gitea repo-level secret (or instance-level) β€” Settings β†’ Secrets + - Commit: _none (configuration check)_ + - Status: `>` +- [ ] **P4.4** Dry-run the workflow: `workflow_dispatch` with `dry_run: true` on a branch + - Commit: `` (the workflow file commit on a branch) + - Status: `` +- [ ] **P4.5** Merge workflow to `main` + - Commit: `` + - Status: `` + +### P5 β€” First real release through the new pipeline + +> Detail: [Β§4 of publish workflow doc](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md#4-releasing-a-new-package-version-operator-workflow) + +- [ ] **P5.1** Coordinate with human: which package to bump for the first real release? (Suggestion: lowest-risk one β€” `@bytelyst/errors` or similar with no consumers' tests depending on a version bump.) + - Commit: _none (decision)_ + - Status: `` +- [ ] **P5.2** Bump version, commit, tag, push to BOTH `origin` and `gitea` + - Commit: `` + - Status: `` +- [ ] **P5.3** Watch the workflow run on both Giteas; verify both succeed + - Commit: _none_ + - Status: `` +- [ ] **P5.4** **Cross-Gitea SHA1 comparison** for the real release (same check as P3.6) + - Commit: _none_ + - Status: `` +- [ ] **P5.5** From a consumer repo (suggest `learning_ai_clock` since you have it open), `pnpm update @bytelyst/` + `pnpm install` + `pnpm typecheck` + - Commit: _none (verification)_ + - Status: `` + +### P6 β€” Review handoff (human reviews after Codex finishes) + +When all phases above are checked, the agent fills in this section and stops: + +- [ ] **P6.1** Roadmap fully ticked through P5.5 +- [ ] **P6.2** Final report summary (fill below) +- [ ] **P6.3** Human reviewed and approved + +--- + +## πŸ“Š Final report (Codex fills in when P0–P5 complete) + +**Runner installation:** + +- Runner name: `` +- Labels: `` +- Gitea instance URL: `` +- Service status: `` +- act_runner version: `` +- Docker image used: `node:20-bookworm@sha256:` + +**E2E validation (P3):** + +- Workflow run URL: `` +- Cross-Gitea SHA match: `<βœ…/❌>` +- Throwaway package fully cleaned up: `` + +**First real release (P5):** + +- Package + version: `<@bytelyst/foo v1.2.3>` +- Hostinger workflow run: `` +- Corp workflow run: `` +- Cross-Gitea SHA match: `<βœ…/❌>` +- Consumer verification: `` + +**Architectural invariant verdict:** `` + +**Surprises / deviations from the plan:** + +- `` +- `` + +**Recommendations for the human:** + +- `` +- `` + +--- + +## πŸ” Review checklist for the human (after Codex hands off) + +When Codex marks P6.2 complete, the human verifies: + +- [ ] **R1** Final report (above) is filled in with no `` strings +- [ ] **R2** Both cross-Gitea SHA matches (P3.6 + P5.4) are βœ… +- [ ] **R3** `systemctl status gitea-act-runner.service` on Hostinger VM is `active (running)` +- [ ] **R4** Gitea admin UI shows runner as Idle and recently seen +- [ ] **R5** `.gitea/workflows/publish-packages.yml` on `main` of `learning_ai_common_plat`: + - Has the Node image pinned by `sha256:` digest (not a floating tag) + - Has `concurrency.cancel-in-progress: false` + - Mounts `~/.gitea_npm_token` as a read-only volume (not in env vars or logs) +- [ ] **R6** The throwaway `@bytelyst/_runner-e2e-test` package is **gone from both Gitea registries** (visit Packages UI to confirm) +- [ ] **R7** No leftover branches: `runner/gitea-smoke`, `runner/gitea-e2e` deleted from both `origin` and `gitea` remotes +- [ ] **R8** A consumer repo can `pnpm install` against either Gitea without lockfile churn (run the corp-network test and the home-network test if possible) +- [ ] **R9** This roadmap doc itself has no surprises in the "Surprises / deviations" section that need follow-up + +Sign-off: + +- Reviewed by: `` +- Date: `` +- Approved: `` + +--- + +## πŸ›  Operating notes for Codex + +### How to commit roadmap updates + +When you tick a checkbox, write the commit message like: + +``` +chore(roadmap): mark P1.6 complete β€” act_runner systemd service active + +Service is running and journal shows "Polling for tasks". See +docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md for the full tracker. +``` + +When you fill in a commit hash field for a code change, use the **short SHA** (7 chars) of the commit that performed the work β€” **not** the SHA of the roadmap-update commit itself. Example: + +``` +- [x] **P3.1** Create throwaway @bytelyst/_runner-e2e-test package + - Commit: abc1234 + - Status: branch pushed to both gitea and origin +``` + +### When to ask the human + +Stop and ask if: + +- A pre-flight check fails or surprises you (P0). +- The cross-Gitea SHA comparison fails (P3.6 or P5.4) β€” don't paper over this; it's the load-bearing invariant. +- You need to deviate from the plan in a non-trivial way (e.g., the Docker image digest isn't available, a step in the underlying doc doesn't work as written). +- The human's earlier answers in P0 turn out to be wrong (e.g., they said instance-level scope but you only have repo admin). + +For minor things (e.g., a typo in the underlying doc, an extra package installation step), proceed and note it in "Surprises / deviations". + +### What you should NEVER do + +- Skip P3.6 or P5.4 (cross-Gitea SHA checks). +- Publish to either Gitea outside of the workflow you just built β€” manual publishes break the invariant. +- Leave the throwaway test package in either Gitea registry. +- Force-push the roadmap file (always normal commits with descriptive messages). +- Mark something `[x]` if it didn't actually fully succeed. Use `[ ] FAILED: ` instead, and stop. + +--- + +## πŸ“œ Change log (auto-maintained by Codex via roadmap-update commits) + +| Date | Phase | Action | Commit | +| -------------------- | ----- | ------------------------ | -------- | +| `` | P0.1 | Pre-flight checks passed | _system_ | +| | | | |