cms-plugins/CLAUDE.md

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
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.