m/projax
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
311cf943bc1be7f55b9072b127bf196e46fea191
projax/CLAUDE.md
mAi dfa81fd58e feat(phase 3p): bake git SHA into binary + surface on /healthz 
Closes the silent-deploy-rot gap caught by Phase 3n's triage. The
problem: a missing Gitea webhook left 11 commits stuck on an old
container while /healthz kept reporting 200 from the stale binary. With
no commit-level evidence on the wire, "deploy rolled" was unverifiable.

Mechanism:
- Dockerfile installs git, reads `git rev-parse --short HEAD` at build
  time, injects via `-ldflags="-X main.gitCommit=<sha>"`. Works under
  Dokploy's `git clone --depth 1` flow (the .git/ folder is in the
  build context) and under plain `docker build .` (same). Local
  `go run` falls back to "unknown".
- main.gitCommit assigns to web.Server.Version in main().
- /healthz now emits two lines: "ok" and "version: <sha>". Endpoint
  remains unauthenticated so any worker / monitor can verify "deploy
  rolled" without a session.

CLAUDE.md gets a mandatory "Post-deploy verification" section: after
every push, compare `git rev-parse --short HEAD` against
`curl /healthz | tail -1`. Mismatch = webhook broken; inspect Gitea
hook 172 (URL pattern `http://mlake.horse-ayu.ts.net:3000/api/deploy/
<refreshToken>` per the working webhooks on m/msbls.de + m/flexsiebels.de).

TestHealthzSurfacesVersion regression-guards the new line. Existing
TestHealthz updated to accept the multi-line body.
2026-05-16 15:35:28 +02:00

4.1 KiB
Raw Blame History

projax — Project Instructions

Purpose

Data backbone for m's complete self-management — projects (digital + physical + strategic + life themes), tasks, lifecycle, milestones. Multiple interfaces consume it. No interface is canonical; each is a view.

Memory group_id: projax Live spec: docs/design.md (PRD, schema, migration plan, deferred phases)

Architecture principles

  1. Model first, interfaces second. The data model is the asset; UIs are replaceable.
  2. First-class non-code projects. Greenhouse construction, household chores, career positioning, sport goals — same model as code projects.
  3. No CLI required. m has explicitly opted out of CLI-first. Interfaces are visual / API / Otto-mediated.
  4. Subsumes existing scattered state. mai.projects (adapter view today), Gitea issues, CalDAV tasks, mBrian topics. Migration not greenfield isolation.
  5. Otto is a consumer, not an owner. Otto-PWA renders projax data; otto coordinates work based on projax; otto does not define projax.

Tech stack (Phase 1)

  • Backend: Go single binary. pgx for Postgres. html/template + HTMX (CDN), no JS build step. Static assets and migrations bundled with embed.
  • Database: msupabase, schema projax (new). View projax.items_unified reads across projax.* + mai.projects. RLS off for v1 (single-user, Tailscale-only).
  • Hosting: Dokploy on mlake, domain projax.msbls.de, Tailscale-only.
  • Tests: go test ./... against SUPABASE_DATABASE_URL (skips when unset).

Layout

cmd/projax/        main entrypoint (pool, migrate, serve)
db/                migrations (embedded) + runner + integration tests
store/             pgx-backed data access
web/               handlers, templates, static
deploy/dokploy.yaml reference manifest for projax.msbls.de
docs/design.md     PRD — the source of truth for behaviour

Branch strategy

  • main = production-deployable
  • feat/* / fix/* — short-lived
  • No dev branch initially (small project)
  • --no-ff merges to main

Post-deploy verification (mandatory)

After every git push origin main, verify the new binary actually rolled — do NOT trust /healthz: ok alone. The pre-3p Phase 3n triage caught 11 commits silently stuck on an old container because the Gitea webhook was missing and healthz kept reporting 200 from the stale binary. The check:

git rev-parse --short HEAD                              # what you just pushed
curl -s https://projax.msbls.de/healthz | tail -1       # "version: <sha>"

If the SHAs match, the deploy rolled. If they don't, the webhook is broken — inspect https://mgit.msbls.de/api/v1/repos/m/projax/hooks (curl --netrc) and confirm hook id 172 exists pointing at http://mlake.horse-ayu.ts.net:3000/api/deploy/<refreshToken>. The healthz endpoint exposes Server.Version (populated from main.gitCommit via Dockerfile-time -ldflags="-X main.gitCommit=..." reading git rev-parse --short HEAD).

Status

  • PRD landed (docs/design.md, 2026-05-15) — schema, lifecycle, interface contracts settled.
  • Phase 1 underway: schema + path trigger + adapter view + Go server + tree/detail/new/classify pages + Docker/Dokploy + README all on a feature branch.
  • Phase 2 (CalDAV + Gitea ingest) and Phase 3 (Excalidraw / MCP / Otto-PWA) are scoped in docs/design.md but not started.

When a phase-1 follow-up surfaces (auth, hiding mai.projects test rows, mBrian topic-hub auto-link, …), file it against docs/design.md §8 first, then split into commits.

Out of scope (still)

  • Multi-user
  • Push notifications + background sync (Otto-PWA's domain)
  • Public exposure
  • Generic SaaS-product instincts
  • CLI surface (m has explicitly opted out)

Refs

  • docs/design.md — live spec (this is the source of truth)
  • mai.projects schema (msupabase) — primary current state (read-only adapted via projax.items_unified)
  • mBrian conventions (topic-hub pattern) — relevant for non-code project tracking, deferred to Phase 3
  • otto session 2026-05-15 — inventory of where project data lives today, justifying this project's existence
  • ~/.claude/CLAUDE.md § Git Strategy, Channel Routing, Memory Protocol