docs: add a name mnemonic to every module README and the root modules table
This commit is contained in:
52
README.md
52
README.md
@@ -89,32 +89,32 @@ The `migrate`, `migrate:status`, `migrate:rollback`, `serve` and admin commands
|
||||
|
||||
## Modules
|
||||
|
||||
| Module | Purpose |
|
||||
|--------|---------|
|
||||
| [backpack](modules/backpack/README.md) | Per-instance application container that holds the configuration, a typed service registry, the event bus and the set of activated plugins. |
|
||||
| [beachcomber](modules/beachcomber/README.md) | Search index sync for GORM models: after-commit upserts and deletes through a pluggable engine, gated by an application kill-switch. |
|
||||
| [boardwalk](modules/boardwalk/README.md) | HTTP handler that serves the embedded admin SPA build under a configurable path prefix. |
|
||||
| [bonfire](modules/bonfire/README.md) | Declarative console commands for the `summer` tool and application binaries, adapted to Cobra with typed input, prompts and styled output. |
|
||||
| [bouncer](modules/bouncer/README.md) | Authentication for SummerCMS: HS256 JWT minting, verification and refresh, request guards, a revoked-token blacklist and bcrypt password helpers. |
|
||||
| [cabana](modules/cabana/README.md) | Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filter and relation definitions at boot and serves them as a JSON admin API next to the embedded admin SPA. |
|
||||
| [compass](modules/compass/README.md) | Layered YAML configuration with per-environment directories, `SUMMER_` environment overrides, embedded plugin defaults and dot-path access. |
|
||||
| [conga](modules/conga/README.md) | Background jobs on River over the shared Postgres pool: transactional dispatch, a `summer_jobs` progress record, in-process or dedicated workers, and a wall-clock scheduler. |
|
||||
| [festival](modules/festival/README.md) | Typed, synchronous event bus with listener priorities, payload collection and stop-when-handled dispatch. |
|
||||
| [fetchguard](modules/fetchguard/README.md) | Guarded outbound HTTP client and fetcher that blocks private and reserved addresses, enforces host, size and timeout limits, and offers an explicit trusted mode for operator-configured endpoints. |
|
||||
| [flare](modules/flare/README.md) | Web Push delivery with VAPID (RFC 8292) and aes128gcm payload encryption (RFC 8291) behind a small Pusher interface. |
|
||||
| [lagoon](modules/lagoon/README.md) | Postgres data layer: the shared GORM connection, per-plugin migrations, model helpers and file attachments. |
|
||||
| [lighthouse](modules/lighthouse/README.md) | Transport-neutral realtime: a publisher interface with pluggable drivers, subscribe-time channel authorization, and model broadcasts enqueued in the write transaction. |
|
||||
| [pact](modules/pact/README.md) | Capability interfaces that compiled plugins implement to contribute routes, config, migrations, middleware, commands, admin screens, translations, mail templates and jobs. |
|
||||
| [party](modules/party/README.md) | Compiled plugin registry that orders plugins by their dependencies and runs their Register and Boot lifecycle. |
|
||||
| [phrasebook](modules/phrasebook/README.md) | Namespaced translation catalogs loaded from plugin YAML, with locale fallback, placeholder interpolation and CLDR pluralization. |
|
||||
| [postcard](modules/postcard/README.md) | Transactional mail from plugin-owned Markdown templates and layouts, delivered through a memory, log or SMTP driver. |
|
||||
| [sunrise](modules/sunrise/README.md) | Bootstrap script that installs the summer CLI and creates a new SummerCMS application, or updates an existing one, in one command, embedded so it is versioned with the framework. |
|
||||
| [sunscreen](modules/sunscreen/README.md) | Credential-redacting slog handler that keeps API keys, tokens and passwords out of application logs. |
|
||||
| [surf](modules/surf/README.md) | HTTP routing for SummerCMS: collects plugin routes and named middleware into a `net/http` ServeMux with constraints, rate limiting, body limits, CORS and panic recovery, and provides the `serve` and `route:list` commands. |
|
||||
| [tide](modules/tide/README.md) | HTTP parity toolkit that records request and response fixtures from a reference backend, replays them against a new one and reports normalized differences. |
|
||||
| [towel](modules/towel/README.md) | Request-scoped actor, organization, collection and locale values carried through `context.Context`. |
|
||||
| [wire](modules/wire/README.md) | JSON response helpers and value types that keep API bodies byte-compatible with a PHP (WinterCMS/Laravel) backend. |
|
||||
| [wristband](modules/wristband/README.md) | An OAuth authorization server for MCP clients: RFC 8414 metadata, RFC 7591 dynamic client registration, the authorization-code flow with PKCE, consent operations and refresh-token rotation over application-supplied storage. |
|
||||
| Module | Purpose | Name mnemonic |
|
||||
|--------|---------|---------------|
|
||||
| [backpack](modules/backpack/README.md) | Per-instance application container that holds the configuration, a typed service registry, the event bus and the set of activated plugins. | The one bag you pack for the beach; it carries everything the application needs: configuration, services, events and plugins. |
|
||||
| [beachcomber](modules/beachcomber/README.md) | Search index sync for GORM models: after-commit upserts and deletes through a pluggable engine, gated by an application kill-switch. | A beachcomber searches the shore for finds; this module keeps the search index in step so content can be found. |
|
||||
| [boardwalk](modules/boardwalk/README.md) | HTTP handler that serves the embedded admin SPA build under a configurable path prefix. | The walkway along the beach front; it is the path admins take into the admin SPA. |
|
||||
| [bonfire](modules/bonfire/README.md) | Declarative console commands for the `summer` tool and application binaries, adapted to Cobra with typed input, prompts and styled output. | The evening fire where everyone gathers; the command line is where you sit down and fire off commands. |
|
||||
| [bouncer](modules/bouncer/README.md) | Authentication for SummerCMS: HS256 JWT minting, verification and refresh, request guards, a revoked-token blacklist and bcrypt password helpers. | Checks IDs at the beach club door; it authenticates requests and turns away the ones without a valid token. |
|
||||
| [cabana](modules/cabana/README.md) | Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filter and relation definitions at boot and serves them as a JSON admin API next to the embedded admin SPA. | The beach hut where the staff run the beach; it is the admin backend. |
|
||||
| [compass](modules/compass/README.md) | Layered YAML configuration with per-environment directories, `SUMMER_` environment overrides, embedded plugin defaults and dot-path access. | Points you the right way; configuration tells the application how to behave in each environment. |
|
||||
| [conga](modules/conga/README.md) | Background jobs on River over the shared Postgres pool: transactional dispatch, a `summer_jobs` progress record, in-process or dedicated workers, and a wall-clock scheduler. | A line of dancers moving one after another; jobs queue up and are worked through in order. |
|
||||
| [festival](modules/festival/README.md) | Typed, synchronous event bus with listener priorities, payload collection and stop-when-handled dispatch. | A summer festival announces events and the crowd reacts; it is the event bus. |
|
||||
| [fetchguard](modules/fetchguard/README.md) | Guarded outbound HTTP client and fetcher that blocks private and reserved addresses, enforces host, size and timeout limits, and offers an explicit trusted mode for operator-configured endpoints. | A lifeguard for outbound fetches; it watches every request the application sends out and stops the dangerous ones. |
|
||||
| [flare](modules/flare/README.md) | Web Push delivery with VAPID (RFC 8292) and aes128gcm payload encryption (RFC 8291) behind a small Pusher interface. | A signal flare reaches people far away; it sends Web Push notifications to browsers. |
|
||||
| [lagoon](modules/lagoon/README.md) | Postgres data layer: the shared GORM connection, per-plugin migrations, model helpers and file attachments. | Calm, deep water where everything settles; it is the database layer where data is stored. |
|
||||
| [lighthouse](modules/lighthouse/README.md) | Transport-neutral realtime: a publisher interface with pluggable drivers, subscribe-time channel authorization, and model broadcasts enqueued in the write transaction. | Beams a signal out to everyone watching; it broadcasts realtime messages to subscribers. |
|
||||
| [pact](modules/pact/README.md) | Capability interfaces that compiled plugins implement to contribute routes, config, migrations, middleware, commands, admin screens, translations, mail templates and jobs. | An agreement both sides keep; it holds the interfaces a plugin agrees to implement. |
|
||||
| [party](modules/party/README.md) | Compiled plugin registry that orders plugins by their dependencies and runs their Register and Boot lifecycle. | The guest list and the order people arrive in; it registers plugins and boots them in dependency order. |
|
||||
| [phrasebook](modules/phrasebook/README.md) | Namespaced translation catalogs loaded from plugin YAML, with locale fallback, placeholder interpolation and CLDR pluralization. | What you pack to speak the local language on holiday; it holds the translations. |
|
||||
| [postcard](modules/postcard/README.md) | Transactional mail from plugin-owned Markdown templates and layouts, delivered through a memory, log or SMTP driver. | What you send home in summer; it delivers the application's mail. |
|
||||
| [sunrise](modules/sunrise/README.md) | Bootstrap script that installs the summer CLI and creates a new SummerCMS application, or updates an existing one, in one command, embedded so it is versioned with the framework. | The start of a summer day; it starts a new application, or updates one, in one command. |
|
||||
| [sunscreen](modules/sunscreen/README.md) | Credential-redacting slog handler that keeps API keys, tokens and passwords out of application logs. | Protects you from exposure; it keeps secrets out of the logs. |
|
||||
| [surf](modules/surf/README.md) | HTTP routing for SummerCMS: collects plugin routes and named middleware into a `net/http` ServeMux with constraints, rate limiting, body limits, CORS and panic recovery, and provides the `serve` and `route:list` commands. | Catching the incoming waves; it routes incoming HTTP requests to their handlers. |
|
||||
| [tide](modules/tide/README.md) | HTTP parity toolkit that records request and response fixtures from a reference backend, replays them against a new one and reports normalized differences. | The tide goes out and comes back, and you compare the waterline; it records traffic from one backend, replays it against another and compares. |
|
||||
| [towel](modules/towel/README.md) | Request-scoped actor, organization, collection and locale values carried through `context.Context`. | You carry it everywhere and it marks your spot; it carries the actor, organization and locale through each request. |
|
||||
| [wire](modules/wire/README.md) | JSON response helpers and value types that keep API bodies byte-compatible with a PHP (WinterCMS/Laravel) backend. | What goes over the wire; it keeps response bodies byte-for-byte the same as the PHP backend's. |
|
||||
| [wristband](modules/wristband/README.md) | An OAuth authorization server for MCP clients: RFC 8414 metadata, RFC 7591 dynamic client registration, the authorization-code flow with PKCE, consent operations and refresh-token rotation over application-supplied storage. | The festival wristband that lets you in for the event; it issues OAuth access for MCP clients. |
|
||||
|
||||
## Using SummerCMS in an application
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@ Per-instance application container that holds the configuration, a typed service
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/backpack"`
|
||||
|
||||
**Name:** The one bag you pack for the beach; it carries everything the application needs: configuration, services, events and plugins.
|
||||
|
||||
## Overview
|
||||
|
||||
`backpack` plays the role of the Laravel service container that WinterCMS plugins reach through `App::make` and singleton bindings, without any process-global state: every `backpack.App` is independent, so tests and multiple instances in one process do not interfere. The generated `main` of an application loads configuration with [compass](../compass/README.md), creates the container with `backpack.New`, and hands it to [party](../party/README.md), which passes it to every plugin's Register and Boot. `backpack` deliberately does not import `party`, which keeps the dependency graph acyclic.
|
||||
|
||||
@@ -6,6 +6,8 @@ Search index sync for GORM models: after-commit upserts and deletes through a pl
|
||||
|
||||
`import _ "git.golem15.com/golem15/summercms/modules/beachcomber/typesense"`
|
||||
|
||||
**Name:** A beachcomber searches the shore for finds; this module keeps the search index in step so content can be found.
|
||||
|
||||
## Overview
|
||||
|
||||
beachcomber is the SummerCMS counterpart of Laravel Scout as WinterCMS applications use it with `queue=false`. A model opts in by implementing `beachcomber.Searchable`. After a create, update or delete of such a model commits, the row is reloaded by primary key and its document is upserted into the engine's index, or removed from it. Sync runs inline in the writing goroutine, bounded by the engine's request timeout, and is never fatal: a failure is logged and the write stays committed.
|
||||
|
||||
@@ -4,6 +4,8 @@ HTTP handler that serves the embedded admin SPA build under a configurable path
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/boardwalk"`
|
||||
|
||||
**Name:** The walkway along the beach front; it is the path admins take into the admin SPA.
|
||||
|
||||
## Overview
|
||||
|
||||
`boardwalk` embeds the compiled admin SPA (`dist/`, produced by `npm --prefix admin run build`) into the binary and serves it. The build is path-agnostic: `index.html` carries a placeholder token that the handler replaces once, at construction, with the prefix the admin is mounted under, so one build works at any backend URI. [cabana](../cabana/README.md) mounts it when it activates the admin routes. It stands in for the server-rendered backend layouts of WinterCMS, which the Go port replaces with a single-page app.
|
||||
|
||||
@@ -4,6 +4,8 @@ Declarative console commands for the `summer` tool and application binaries, ada
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/bonfire"`
|
||||
|
||||
**Name:** The evening fire where everyone gathers; the command line is where you sit down and fire off commands.
|
||||
|
||||
## Overview
|
||||
|
||||
bonfire is the console layer of SummerCMS. Plugins and framework modules describe commands as plain `bonfire.Command` values (name, flags, arguments and a run function), and `bonfire.NewRoot` turns a slice of them into a Cobra root command. Commands never touch Cobra directly: they read arguments through `bonfire.Input` and write through `bonfire.Output`, which also provides tables, spinners, progress bars and interactive prompts. It is the counterpart of WinterCMS's artisan console commands (`registerConsoleCommand` and Laravel's `Illuminate\Console\Command` output helpers).
|
||||
|
||||
@@ -4,6 +4,8 @@ Authentication for SummerCMS: HS256 JWT minting, verification and refresh, reque
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/bouncer"`
|
||||
|
||||
**Name:** Checks IDs at the beach club door; it authenticates requests and turns away the ones without a valid token.
|
||||
|
||||
## Overview
|
||||
|
||||
bouncer decides who is making a request. Guards (`bouncer.Guard`, `bouncer.CredentialGuard`) turn an `*http.Request` into a `bouncer.Principal`; a `bouncer.Registry` holds named guards that plugins register and turns each one into HTTP middleware that stores the principal on the request context. The JWT side issues and checks HS256 tokens for two audiences, frontend users (`bouncer.AudienceUser`) and admin users (`bouncer.AudienceBackend`), with a refresh flow and a jti blacklist compatible with tokens issued by the PHP jwt-auth library. It is the counterpart of WinterCMS's Auth and BackendAuth facades and the JWT auth layer used by API plugins.
|
||||
|
||||
@@ -4,6 +4,8 @@ Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filte
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/cabana"`
|
||||
|
||||
**Name:** The beach hut where the staff run the beach; it is the admin backend.
|
||||
|
||||
## Overview
|
||||
|
||||
`cabana` is the SummerCMS counterpart of WinterCMS's backend: controllers with the List, Form and Relation behaviors, their `config_list.yaml`, `config_form.yaml`, `config_filter.yaml` and `config_relation.yaml` files, the model `columns.yaml` and `fields.yaml`, backend users, roles and permissions, settings models and backend navigation. Plugins declare admin controllers through the [pact](../pact/README.md) capability interfaces and embed their YAML; `cabana.Activate` compiles all of it once at boot, fails fast on any schema error, and returns the admin routes that [surf](../surf/README.md) mounts under the admin prefix (`backend.uri`, default `/backend`). The JSON API lives under `<prefix>/api/v1`, and every other path under the prefix serves the admin SPA from [boardwalk](../boardwalk/README.md).
|
||||
|
||||
@@ -4,6 +4,8 @@ Layered YAML configuration with per-environment directories, `SUMMER_` environme
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/compass"`
|
||||
|
||||
**Name:** Points you the right way; configuration tells the application how to behave in each environment.
|
||||
|
||||
## Overview
|
||||
|
||||
`compass` is the SummerCMS counterpart of WinterCMS's `config/*.php` files, per-environment config directories, `.env` support and `Config::get('app.name')`. It merges several layers into one tree built on koanf, and every key is read with a dot path such as `app.name`. Plugin defaults live under the bare plugin ID (`acme.blog.posts_per_page`) instead of WinterCMS's `acme.blog::posts_per_page`. The generated `main` of an application calls `compass.Load("config")` and hands the result to [backpack](../backpack/README.md); [party](../party/README.md) merges plugin defaults into it during activation.
|
||||
|
||||
@@ -4,6 +4,8 @@ Background jobs on River over the shared Postgres pool: transactional dispatch,
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/conga"`
|
||||
|
||||
**Name:** A line of dancers moving one after another; jobs queue up and are worked through in order.
|
||||
|
||||
## Overview
|
||||
|
||||
conga is the SummerCMS counterpart of the WinterCMS queue plus the apparatus job manager. Plugins describe background work as typed job functions wrapped by `conga.Job` and return them from `pact.HasJobs`, so plugin code never imports River. A caller dispatches a job with `conga.Manager.Dispatch` inside its own write transaction: the `summer_jobs` record row and the River job are written on the same `*sql.Tx`, so a rollback leaves neither behind. River only executes the work; the record row is what progress, outcome and cancellation reads use.
|
||||
|
||||
@@ -4,6 +4,8 @@ Typed, synchronous event bus with listener priorities, payload collection and st
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/festival"`
|
||||
|
||||
**Name:** A summer festival announces events and the crowd reacts; it is the event bus.
|
||||
|
||||
## Overview
|
||||
|
||||
`festival` is the SummerCMS counterpart of WinterCMS's `Event::listen` and `Event::fire`, the mechanism plugins use to extend each other without direct calls. Events are routed by their Go type rather than by a string name, so a listener registered for `*PostPublished` receives exactly that type, and a payload mismatch is a compile error. Each application owns one bus: [backpack](../backpack/README.md) creates it in `backpack.New` and exposes it as `backpack.App.Events`, and plugins register listeners from their Boot step.
|
||||
|
||||
@@ -4,6 +4,8 @@ Guarded outbound HTTP client and fetcher that blocks private and reserved addres
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/fetchguard"`
|
||||
|
||||
**Name:** A lifeguard for outbound fetches; it watches every request the application sends out and stops the dangerous ones.
|
||||
|
||||
## Overview
|
||||
|
||||
`fetchguard` is the framework's server-side request forgery guard for fetching URLs that come from users or third parties, such as a remote image address. Every call takes a `fetchguard.Policy` that either restricts the target to an allow list of hosts or permits any public host; in both modes the dial-time check refuses private, loopback, link-local, carrier-grade NAT, documentation, multicast and other reserved IPv4 and IPv6 ranges, including IPv4 embedded in NAT64 and 6to4 addresses. Failures come back as a `fetchguard.Error` carrying one `fetchguard.Reason` from a closed set, so callers can map them onto stable API error codes. WinterCMS has no dedicated counterpart; plugins there typically used Guzzle with hand-written checks.
|
||||
|
||||
@@ -4,6 +4,8 @@ Web Push delivery with VAPID (RFC 8292) and aes128gcm payload encryption (RFC 82
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/flare"`
|
||||
|
||||
**Name:** A signal flare reaches people far away; it sends Web Push notifications to browsers.
|
||||
|
||||
## Overview
|
||||
|
||||
flare sends browser push notifications. Push is a separate channel from realtime: `lighthouse` publishes to clients that hold an open connection, while flare hands a message to the browser vendor's push service, which wakes the browser even when no page is open.
|
||||
|
||||
@@ -6,6 +6,8 @@ Postgres data layer: the shared GORM connection, per-plugin migrations, model he
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/lagoon/attach"`
|
||||
|
||||
**Name:** Calm, deep water where everything settles; it is the database layer where data is stored.
|
||||
|
||||
## Overview
|
||||
|
||||
`lagoon` is the WinterCMS models and migrations counterpart: it opens the one `*sql.DB` pool (pgx stdlib driver) that GORM and the rest of the application share, runs each plugin's gormigrate set in its own history table, and ports the Eloquent model conventions that WinterCMS plugins rely on, such as `$fillable`, `$hidden`, `$jsonable`, encrypted casts and Laravel-style validation rules. Its `attach` subpackage ports WinterCMS's `system_files` attachments, storing originals and lazily generated thumbnails in a gocloud.dev blob bucket. The application binary gets the migrate and key commands from `lagoon.RuntimeCommands`.
|
||||
|
||||
@@ -6,6 +6,8 @@ Transport-neutral realtime: a publisher interface with pluggable drivers, subscr
|
||||
|
||||
`import _ "git.golem15.com/golem15/summercms/modules/lighthouse/centrifugo"`
|
||||
|
||||
**Name:** Beams a signal out to everyone watching; it broadcasts realtime messages to subscribers.
|
||||
|
||||
## Overview
|
||||
|
||||
lighthouse is the SummerCMS counterpart of the WinterCMS websockets plugin. The package itself knows no transport. It owns the interfaces application code writes against, and a driver package supplies the transport. A driver registers itself from its `init` function, the way `database/sql` drivers do, and the application picks one with `realtime.driver`.
|
||||
|
||||
@@ -4,6 +4,8 @@ Capability interfaces that compiled plugins implement to contribute routes, conf
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/pact"`
|
||||
|
||||
**Name:** An agreement both sides keep; it holds the interfaces a plugin agrees to implement.
|
||||
|
||||
## Overview
|
||||
|
||||
`pact` is the contract layer between plugins and the framework. It holds interfaces and plain data types, with no behaviour of its own. A plugin opts into a capability by implementing one of the `Has*` interfaces, and the framework package that owns the capability discovers it with a type assertion ([party](../party/README.md) for config, [surf](../surf/README.md) for routes and middleware, [lagoon](../lagoon/README.md) for migrations, [cabana](../cabana/README.md) for admin controllers, [conga](../conga/README.md) for jobs and schedules). It replaces the `register*()` methods of a WinterCMS PluginBase (`registerPermissions`, `registerNavigation`, `registerSettings` and so on) with small, separately implementable interfaces.
|
||||
|
||||
@@ -4,6 +4,8 @@ Compiled plugin registry that orders plugins by their dependencies and runs thei
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/party"`
|
||||
|
||||
**Name:** The guest list and the order people arrive in; it registers plugins and boots them in dependency order.
|
||||
|
||||
## Overview
|
||||
|
||||
`party` is the WinterCMS PluginBase and PluginManager counterpart for plugins compiled into the binary. Each plugin package calls `party.Register` from its `init` function, and the application's generated `main` calls `party.Activate` with the plugin IDs listed in its manifest. Activation validates the selection, sorts it so every plugin comes after the plugins it requires, merges plugin config, runs every Register before any Boot, and wires translations and mail templates in between. Capabilities beyond the lifecycle are declared through the interfaces in [pact](../pact/README.md).
|
||||
|
||||
@@ -4,6 +4,8 @@ Namespaced translation catalogs loaded from plugin YAML, with locale fallback, p
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/phrasebook"`
|
||||
|
||||
**Name:** What you pack to speak the local language on holiday; it holds the translations.
|
||||
|
||||
## Overview
|
||||
|
||||
phrasebook owns every translatable string in a SummerCMS application. At boot, `phrasebook.Activate` loads the framework's own strings plus the `lang/` tree of every plugin that implements `pact.HasLang`, applies overrides from plugins that implement `pact.HasLangOverrides`, and publishes a single `phrasebook.Translator` on the `backpack.App`. Keys use the WinterCMS form `namespace::group.dot.path`, and message syntax follows Laravel (`:name` placeholders, `|` plural pipes), so it is the counterpart of WinterCMS's `Lang::get` / `trans_choice` and plugin `lang/` directories.
|
||||
|
||||
@@ -4,6 +4,8 @@ Transactional mail from plugin-owned Markdown templates and layouts, delivered t
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/postcard"`
|
||||
|
||||
**Name:** What you send home in summer; it delivers the application's mail.
|
||||
|
||||
## Overview
|
||||
|
||||
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates and layouts as the plugin boots. Callers then send a template by its dotted name with a map of variables. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
|
||||
|
||||
@@ -4,6 +4,8 @@ Bootstrap script that installs the summer CLI and creates a new SummerCMS applic
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/sunrise"`
|
||||
|
||||
**Name:** The start of a summer day; it starts a new application, or updates one, in one command.
|
||||
|
||||
## Overview
|
||||
|
||||
`sunrise` holds `new.sh`, the script behind the one-liner served at https://summercms.io/new:
|
||||
|
||||
@@ -4,6 +4,8 @@ Credential-redacting slog handler that keeps API keys, tokens and passwords out
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/sunscreen"`
|
||||
|
||||
**Name:** Protects you from exposure; it keeps secrets out of the logs.
|
||||
|
||||
## Overview
|
||||
|
||||
`sunscreen` wraps any `log/slog` handler and rewrites every record before it is written: values of sensitive attribute keys become `[REDACTED]`, and credential shapes inside messages and string values are scrubbed. It is the SummerCMS counterpart of a Monolog tap that a WinterCMS application wires into its log channels to scrub contexts and messages. Every application `main` that `summer build` generates calls `sunscreen.InstallDefault(os.Stderr)` as its first statement, so the default logger, the standard `log` package and every plugin that falls back to `slog.Default` log through it from the start.
|
||||
|
||||
@@ -4,6 +4,8 @@ HTTP routing for SummerCMS: collects plugin routes and named middleware into a `
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/surf"`
|
||||
|
||||
**Name:** Catching the incoming waves; it routes incoming HTTP requests to their handlers.
|
||||
|
||||
## Overview
|
||||
|
||||
surf turns the routes that plugins declare through `pact.HasRoutes` into one `http.Handler`. `surf.BuildRouter` registers the built-in and plugin middleware, walks every plugin's route declarations through a Laravel-style group builder (`surf.Router`, implementing `pact.Router`), mounts the [cabana](../cabana/README.md) admin, and checks every route at boot; `surf.Assemble` then compiles the result onto a standard library ServeMux. Configuration mistakes such as duplicate routes, unknown middleware names or malformed throttles fail at boot, not on the first request. It is the counterpart of WinterCMS's plugin `routes.php` files with Laravel's `Route::group`, `->middleware()`, `->where()` and `throttle` middleware.
|
||||
|
||||
@@ -4,6 +4,8 @@ HTTP parity toolkit that records request and response fixtures from a reference
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/tide"`
|
||||
|
||||
**Name:** The tide goes out and comes back, and you compare the waterline; it records traffic from one backend, replays it against another and compares.
|
||||
|
||||
## Overview
|
||||
|
||||
`tide` is the acceptance-test engine for porting an existing WinterCMS or other PHP backend to SummerCMS: the reference backend's real responses define the contract, and the Go port must reproduce them. It records YAML fixtures (flows of request and response steps) either by driving a spec against a target or by sitting as a loopback reverse proxy in front of the reference backend while a real client uses it, then replays those fixtures against the port and diffs the responses after masking values that legitimately differ, such as IDs and timestamps. It also checks realtime side effects: a fake Centrifugo recorder captures the publications a backend sends while a flow runs, and broadcast golden files hold them normalised for comparison. Upstream sidecars record the calls a backend makes to outside vendors, through a loopback HTTPS recording proxy, and replay them offline through an asserting fake. The `summer` CLI's parity:proxy, parity:record, parity:replay, parity:broadcasts and parity:upstream commands are thin wrappers around this package. It has no WinterCMS counterpart.
|
||||
|
||||
@@ -4,6 +4,8 @@ Request-scoped actor, organization, collection and locale values carried through
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/towel"`
|
||||
|
||||
**Name:** You carry it everywhere and it marks your spot; it carries the actor, organization and locale through each request.
|
||||
|
||||
## Overview
|
||||
|
||||
`towel` replaces the request-global state that WinterCMS reads through facades (the current locale, the acting user) with explicit values on the request context. Middleware stores a value once, and any code further down the call chain that receives the context reads it back without a global lookup. [surf](../surf/README.md) sets the locale from `Accept-Language` (or the signed-in user's preferred locale) and the organization for every request, [phrasebook](../phrasebook/README.md) reads the locale when it translates, and [cabana](../cabana/README.md) sets it while localizing admin schemas.
|
||||
|
||||
@@ -4,6 +4,8 @@ JSON response helpers and value types that keep API bodies byte-compatible with
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/wire"`
|
||||
|
||||
**Name:** What goes over the wire; it keeps response bodies byte-for-byte the same as the PHP backend's.
|
||||
|
||||
## Overview
|
||||
|
||||
`wire` is the lowest layer of the HTTP stack: it decides how a Go value becomes response bytes. Its helpers reproduce what `json_encode` and Carbon produce in a WinterCMS or Laravel app (unescaped HTML characters, no trailing newline, `+00:00` timestamps, nullable booleans, `[]` rather than `null` for empty lists), so an endpoint ported from PHP returns the same body its existing clients already parse. [surf](../surf/README.md) uses it for the opaque 500 response of its panic recovery, and application handlers use it directly for their JSON responses.
|
||||
|
||||
@@ -4,6 +4,8 @@ An OAuth authorization server for MCP clients: RFC 8414 metadata, RFC 7591 dynam
|
||||
|
||||
`import "git.golem15.com/golem15/summercms/modules/wristband"`
|
||||
|
||||
**Name:** The festival wristband that lets you in for the event; it issues OAuth access for MCP clients.
|
||||
|
||||
## Overview
|
||||
|
||||
wristband implements the protocol side of an OAuth authorization server so an application can let MCP clients (AI assistants and connectors) act on behalf of its users. A `wristband.Server` provides ready-made `net/http` handlers for the metadata, authorize, token and registration endpoints, plus Go methods the application's own consent screen calls. Everything application-specific stays outside the package: persistence arrives through the `wristband.Backend` and `wristband.Tx` interfaces, access tokens are minted by the application's `wristband.AccessTokenIssuer`, and issuer, scopes and lifetimes come from `wristband.Options`. It imports no ORM and no application package. WinterCMS core has no counterpart.
|
||||
|
||||
Reference in New Issue
Block a user