oleks/cms-plugins
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
cms-plugins/CLAUDE.md
T
Oleks 8c119efff8 harden(deploy): apply safe fixes from review report-only items 
- #3 Liveness probe targets full SSR DB-querying / route, coupling pod liveness to SQLite
- #4 Chart values-staging/production.yaml are dead config under Flux; drift trap
- #6 tsconfig includes gitignored emdash-env.d.ts that only the dev server generates
- #7 Dockerfile package-lock glob + npm install fallback can silently build an unlocked image
- #8 Dockerfile creates runtime user without pinning its GID
- #9 entrypoint.sh gates `emdash init` on data.db absence, skipping migrations on PVC reuse
- #10 pullPolicy: Always vs digest pinning
- #11 Dockerfile state symlinks contradict the STATE_DIR contract; Dockerfile does not set ENV STATE_DIR
- #12 astro is a production dependency, so npm prune --omit=dev keeps build-only tooling
- #14 Two ImageUpdateAutomations write back to the same anton-helm-workloads main branch
- #16 memoryCache provider is per-process; correctness depends implicitly on replicas:1
- #17 Root catch-all [slug].astro couples nav links to pages-collection rows + DB hit per unmatched path
- #18 Detail pages render a 200-style body under a 404 status and have no try/catch around getEmDash* calls
- #19 vite allowedHosts hardcodes ddev hostnames (dev-only; no prod impact)
2026-06-02 04:50:54 +03:00

4.5 KiB
Raw Permalink Blame History

CLAUDE.md

Guidance for Claude Code agents working in this repository.

What this repo is

A browseable catalog of CMS plugins built on Emdash. Phase 0 — scaffold + chart + pipeline are in place, no live deploy yet. Seeded with the WordPress → Emdash plugin parity matrix from ~/projects/kotkanagrilli.fi/ and ~/projects/emdash.kotkanagrilli.fi/docs/parity.md.

Linked repos

  • ~/projects/kotkanagrilli.fi/ — legacy WordPress site. Do not edit from here. Source of the seeded plugin entries.
  • ~/projects/emdash.kotkanagrilli.fi/ — Emdash replacement for that site. The Dockerfile, Helm chart, Woodpecker pipeline, and DDEV setup in this repo are deliberate copies of that one. Treat it as the reference implementation; deviations should be justified.
  • ~/projects/servers/anton/anton-helm-workloads/ — where the FluxCD HelmReleases for cms-plugins-{staging,production}.kotkanagrilli.fi live. deploy/fleet-overlay/ in this repo is the template set to copy into that repo. Do not commit to anton-helm-workloads without explicit confirmation — secrets need sops-encryption with the right age recipients.
  • ~/projects/servers/fleet/ — personal fleet repo. Owns emdash-kotkanagrilli-{staging,production} but NOT cms-plugins.

Layout

  • app/ — Emdash scaffold (node target, no i18n, no Cloudflare boundary). Three collections in seed/seed.json: cmses, plugins, pages.
  • Dockerfile + docker/entrypoint.sh — production image.
  • deploy/helm/ — the chart Flux pulls from ./deploy/helm on the matching branch.
  • deploy/fleet-overlay/cms-plugins-{staging,production}/ — HelmRelease
    • GitRepository + image-automation + secrets templates ready to drop into anton-helm-workloads.
  • .woodpecker/container.yaml — build pipeline (arm64; deploy target is kotkan).
  • .ddev/ — local dev.
  • DEPLOYMENT.md — full pipeline walkthrough.
  • ARCHITECTURE.md — chart / image / Flux contracts.

Common commands

# Local dev
ddev start                    # https://cms-plugins.ddev.site/
# or, without DDEV:
cd app && npm install && npm run bootstrap && npx emdash dev

# Build production image
docker build -t cms-plugins:dev .

# Typecheck — NOTE: requires app/emdash-env.d.ts, which tsconfig.json
# includes but which is gitignored + untracked. Emdash regenerates it
# ONLY via the dev-server `astro:server:setup` hook, so on a clean
# checkout you must start the dev server once (`npx emdash dev`, then
# stop it) before `astro check` will resolve emdash types. `astro build`
# (the Docker/CI image path) does NOT type-check and is unaffected.
cd app && npm run typecheck

Architectural constraints to respect

  • One repo, one app, node target. No Cloudflare boundary files yet; adding them is a deliberate Phase-N call, not casual work.
  • SQLite single-writer. One replica, pinned to kotkan, local-path PVC. No StatefulSet, no horizontal scale.
  • Chart pulled directly from git by Flux — no helm push step. Chart changes ship in the same commit as the code that needs them.
  • Image is pinned by digest in the HelmRelease. ImageUpdateAutomation rewrites the digest setter; helm upgrade only sees a change because of that. The floating <branch> tag alone wouldn't roll the pod.
  • The legacy WP site keeps running. This repo doesn't migrate kotkanagrilli.fi — it's a catalog ABOUT plugins, not the site itself.

Emdash gotchas (from the kotkanagrilli reference)

  • All content pages must be server-rendered (output: "server"); no getStaticPaths() for CMS content.
  • entry.id is the slug (URLs); entry.data.id is the database ULID (used for API calls / cross-collection refs).
  • Image fields are { src, alt } objects, not strings.
  • Always Astro.cache.set(cacheHint) on pages that query content.
  • Taxonomy names in queries match seed.json's name field exactly.

What NOT to do

  • Don't npm install random kotkanagrilli plugins (the e-commerce ones). This is a catalog, not a store.
  • Don't push to anton-helm-workloads without explicit confirmation — unencrypted secrets would leak.
  • Don't change branch promotion semantics (fast-forward only across develop → staging → production). Mirroring emdash-kotkanagrilli's flow is intentional.
  • Don't commit the dev SQLite DB. data.db / data.db-shm / data.db-wal are dev artifacts (gitignored + dockerignored); they must never live in the source tree. Regenerate via npm run bootstrap (emdash init).
Reference in New Issue View Git Blame Copy Permalink