feat(12.1-01): declared record actions with an applicability rule

- pact.HasAdminRecordActions with AdminRecordAction (Applies, Run)
- config_form.yaml recordActions, compiled fail-loud
- show response meta.actions lists the permitted actions that apply
- POST .../{controller}/{id}/actions/{action}: record loaded and locked
  through the form scope; 404 out of scope, 409 when it does not apply
- RecordActions.vue with confirm and request flow (mounted by plan 02)
- roster fixture, smoke tests, OpenAPI, TS types, READMEs, docs

modules/cabana/README.md

@@ -18,6 +18,7 @@ Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filte
 - Controller assets: a controller implementing `pact.AdminClientAssets` names JS (`.js`, `.mjs`) and CSS files under its plugin's `assets/` directory, Winter's `addJs`/`addCss`. They are read from the plugin's embedded tree at boot (a missing file fails boot; there is no disk override) and listed in the list and form schemas under `assets` as same-origin URLs with a `?v=` content hash. A form with a widget needs at least one JS file.
 - Toolbar actions: `toolbar.buttons` in `config_list.yaml` lists the built-in `create` and `delete` next to names the controller registers through `pact.HasAdminActions`. Registered actions share one namespace with widget actions, `create` and `delete` are reserved, and each toolbar action needs a label. The list schema's `toolbarActions` carries only the actions the requesting administrator may run, with localized labels; an unknown name fails boot.
 - Bulk actions: `bulkActions` in `config_list.yaml` lists names the controller registers through `pact.HasAdminBulkActions`; it needs `showCheckboxes: true`. Bulk actions have their own namespace (`create` and `delete` are reserved there too), and each needs a label. The posted ids are resolved and row-locked through `pact.ListExtendQuery` in one transaction and the action receives the loaded records, never ids: a selection that matches nothing answers `affected: 0` without running the action, and a partial match answers 409 and rolls back. The list schema's `bulkActions` carries the built-in `delete` and only the declared actions the requesting administrator may run, with localized `label` and `confirm`; an unknown or duplicate name fails boot. Each run is logged with the controller, action, administrator and affected count.
+- Record actions: `recordActions` in `config_form.yaml` lists names the controller registers through `pact.HasAdminRecordActions`, a third action namespace with the same reserved names. The show response's `meta.actions` (`cabana.RecordAction` entries with localized `label` and `confirm`) carries only the declared actions the requesting administrator may run and whose `Applies` reports true for the record; the key is absent when none is offered, and create and update responses never carry it. The action route loads the record through `pact.FormExtendQuery` with a row lock in one transaction (one 404 for a missing and an out-of-scope id), checks `Applies` again (409 when it reports false) and then runs the action. An unknown or duplicate name, or an action without a label, fails boot. Each run is logged with the controller, action, administrator and record id.
 - Server-rendered partials: `headerPartial: <name>` in `config_list.yaml` (a strip above the list) and `type: partial` with `path: <name>` in `fields.yaml` render the template `{ConfigDir}/_<name>.htm` with `html/template` against a view model from the controller's `pact.AdminPartialData`. The result reaches the SPA as an allowlisted node tree, never as an HTML string. A missing or unparsable template, a free-form path or a controller without `pact.AdminPartialData` fails boot.
 - Date pickers: a `type: datepicker` field in `fields.yaml` edits a date (`mode: date`, a `lagoon.Date` column), a date and time (`mode: datetime`, the default, a `time.Time` column stored in UTC) or a time of day (`mode: time`, a `lagoon.TimeOfDay` column); pointers to the three types make the value optional. It accepts WinterCMS's `mode`, `format` (a PHP `date()` format, served also as `displayFormat` in the SPA's tokens), `minDate`, `maxDate`, `yearRange`, `firstDay`, `twelveHour` and `ignoreTimezone`; any other key, a format letter with no equivalent, bounds on `mode: time`, `ignoreTimezone` outside `mode: datetime` or a column whose Go type does not match the mode fails boot. The save rechecks `minDate` and `maxDate` on the calendar date and answers 422 on the field. List columns take `type: date` and `type: time` for these columns; when `type` is omitted, a `time.Time` column is compiled as `datetime`, a `lagoon.Date` column as `date` and a `lagoon.TimeOfDay` column as `time`. A struct column that implements `sql.Scanner` or `driver.Valuer` is never taken for a relation.
 - File uploads: a `type: fileupload` field in `fields.yaml` edits an attachOne or attachMany relation the record model declares through `attach.HasRelations` (its `AttachRelations` method) next to `attach.Owner`. The field accepts WinterCMS's `mode` (`image` or `file`), `fileTypes`, `mimeTypes`, `maxFilesize` (megabytes), `maxFiles` (attachMany only), `imageWidth`, `imageHeight`, `thumbOptions` (only `mode`: `auto`, `exact`, `crop` or `fit`), `useCaption` and `prompt`; any other key, an image-mode file type outside jpg, jpeg, png, gif and webp, a name that is not a declared relation or a `maxFilesize` whose file plus 64 KiB of multipart framing exceeds `http.body_limits.upload_bytes` fails boot. Uploads and removals are deferred, as in WinterCMS: the SPA sends a random form session key in the `X-Session-Key` header (`cabana.SessionKeyHeader`) with every file call and with the save, the server keeps the pending work in `deferred_bindings` against that key and the signed-in administrator, and the record's next create or update save applies it inside its transaction. A retry of the same upload may send `X-Upload-Id` so the server returns the already stored file. A save that fails with 422 keeps the pending uploads; another administrator's key matches nothing. The upload route caps the request body at the smaller of `http.body_limits.upload_bytes` and `maxFilesize` plus 64 KiB and answers 413 `payload_too_large` past it; the size, type and image checks run on the server (through `attach.Store`) and answer 422 on the field. A file list (`cabana.FileItem`) carries `url` and `thumb_url` only for a public relation.
@@ -44,6 +45,7 @@ All paths are relative to `<prefix>/api/v1`. A controller ID `vendor.plugin.cont
 | GET, PUT and DELETE `/{vendor}/{plugin}/{controller}/{id}` | Show, update and delete a record (update and delete need a form). |
 | POST `/{vendor}/{plugin}/{controller}/bulk-delete` | Delete a set of records in one transaction; needs `delete` in `toolbar.buttons`. |
 | POST `/{vendor}/{plugin}/{controller}/bulk/{action}` | Run a declared bulk action on `{ids}` in one transaction; answers `{message, affected}`, 409 for a partial selection. |
+| POST `/{vendor}/{plugin}/{controller}/{id}/actions/{action}` | Run a declared record action with an empty `{}` body in one transaction; answers `{message, fill: {}}`, 404 outside the form scope, 409 when the action does not apply. |
 | POST `/{vendor}/{plugin}/{controller}/widgets/{field}` | Run the action of a `type: widget` field with an optional `record_id` and the fill snapshot; answers `{message, fill}`. |
 | POST `/{vendor}/{plugin}/{controller}/toolbar/{action}` | Run a registered toolbar action with an empty `{}` body; answers `{message, fill: {}}`. |
 | GET `/{vendor}/{plugin}/{controller}/partials/{name}` | Render a declared header or form partial as a node tree; `?id=` (form partials only) passes the scoped record to the view model. |
@@ -172,6 +174,9 @@ func (p *Plugin) AdminFS() fs.FS { return adminFS }
 | `cabana.BulkAction` | One entry of a list schema's `bulkActions`: name, localized label and optional confirm text. |
 | `cabana.BulkActionResult` | Answer of the bulk action route: the localized `message` and the `affected` count. |
 | `cabana.AdminBulkAction` | Swag annotation of the bulk action route. |
+| `cabana.RecordAction` | One entry of a record response's `meta.actions`: name, localized label and optional confirm text. |
+| `cabana.CRUDService.RecordAction` | Runs a declared record action on one scoped, locked record. |
+| `cabana.AdminRecordAction` | Swag annotation of the record action route. |
 | `cabana.ExecuteList` | Runs an allowlisted, paginated list query for a controller. |
 | `cabana.RelationService` | Linked, candidate, link and unlink operations of relation managers, child create, show, update and delete (`CreateChild`, `ShowChild`, `UpdateChild`, `DeleteChildren`) and pivot values (`ShowPivot`, `UpdatePivot`); its `SessionKey` makes record id 0 the record being created in that session. |
 | `cabana.SettingsService` | Reads and transactionally updates singleton settings rows. |

modules/cabana/actions.go

@@ -171,6 +171,72 @@ func bulkActionOf(cc *CompiledController, name string) (pact.AdminBulkAction, bo
 	return action, ok
 }
 
+// recordAction serves POST .../{controller}/{id}/actions/{action} (D-10): a
+// registered record action the form's recordActions declares. The record is
+// loaded through the controller's form scope with a row lock inside the
+// action's transaction, so a missing or out-of-scope id is one 404, and an
+// action that no longer applies to the record is a 409.
+func (s *service) recordAction(w http.ResponseWriter, r *http.Request) {
+	s.protect(w, r, func(cc *CompiledController) {
+		name := r.PathValue("action")
+		action, ok := recordActionOf(cc, name)
+		if !ok {
+			WriteError(w, http.StatusNotFound, "not_found", msgNotFound)
+			return
+		}
+		if !s.allowAction(w, r, action.Permissions) {
+			return
+		}
+		id, err := pathID(r)
+		if err != nil {
+			writeCRUDError(w, err)
+			return
+		}
+		in, err := decodeActionRequest(r)
+		if err != nil {
+			writeCRUDError(w, err)
+			return
+		}
+		if in.RecordID != nil || in.Values != nil {
+			writeCRUDError(w, &ValidationError{Details: map[string]any{"body": []string{"A record action takes no record_id or values."}}})
+			return
+		}
+		svc, err := s.crud()
+		if err != nil {
+			WriteError(w, http.StatusInternalServerError, "error", msgServerError)
+			return
+		}
+		result, err := svc.RecordAction(r.Context(), cc, id, name)
+		if err != nil {
+			writeCRUDError(w, err)
+			return
+		}
+		var adminID uint
+		if principal, _ := bouncer.User(r.Context()); principal != nil {
+			adminID = principal.ID
+		}
+		slog.Info("cabana: admin record action", "controller", controllerID(cc), "action", name, "admin_id", adminID, "record_id", id)
+		WriteData(w, http.StatusOK, result, nil)
+	})
+}
+
+// recordActionOf returns the registered record action a form declares under
+// name in recordActions.
+func recordActionOf(cc *CompiledController, name string) (pact.AdminRecordAction, bool) {
+	if cc == nil || cc.Form == nil || builtinToolbarActions[name] {
+		return pact.AdminRecordAction{}, false
+	}
+	declared := false
+	for _, entry := range cc.Form.recordActions {
+		declared = declared || entry == name
+	}
+	if !declared {
+		return pact.AdminRecordAction{}, false
+	}
+	action, ok := cc.RecordActions[name]
+	return action, ok
+}
+
 // allowAction applies an action's own permissions on top of the controller's
 // (already checked by protect). Every action kind shares it: a denial is
 // logged and answered 403.

modules/cabana/admin_openapi.go

@@ -418,6 +418,29 @@ func AdminBulkDelete() {}
 // @Router /{vendor}/{plugin}/{controller}/bulk/{action} [post]
 func AdminBulkAction() {}
 
+// AdminRecordAction documents the declared record action route.
+//
+// @Summary Run a declared record action
+// @Description Runs a record action the controller registers and the form's recordActions declares. The record is loaded and row-locked through the controller's form scope in one transaction (404 when missing or out of scope); an action that does not apply to the record's current state answers 409. The body must be {} and the answer's fill is always empty.
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security BackendBearer
+// @Param vendor path string true "Vendor"
+// @Param plugin path string true "Plugin"
+// @Param controller path string true "Controller"
+// @Param id path integer true "Record id"
+// @Param action path string true "Record action name"
+// @Param body body AdminActionRequest true "Empty object"
+// @Success 200 {object} Envelope[AdminActionResult]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 422 {object} ErrorEnvelope
+// @Router /{vendor}/{plugin}/{controller}/{id}/actions/{action} [post]
+func AdminRecordAction() {}
+
 // AdminActionRequest is the body of a widget or toolbar action. record_id is
 // the record a widget on the update form belongs to (absent on create and
 // always absent for a toolbar action); values is the widget's snapshot of its
@@ -499,6 +522,7 @@ func AdminPartial() {}
 // AdminShow documents the record show route.
 //
 // @Summary Show an admin record
+// @Description meta.labels carries the display labels of relation fields. meta.actions lists the declared record actions the requesting admin may run and that apply to the record's current state; it is absent when none is offered.
 // @Tags admin
 // @Produce json
 // @Security BackendBearer

modules/cabana/contracts.go

@@ -83,6 +83,9 @@ type CompiledController struct {
 	// by name. They have their own namespace next to Actions; create and
 	// delete are reserved there too.
 	BulkActions map[string]pact.AdminBulkAction
+	// RecordActions are the controller's pact.HasAdminRecordActions entries
+	// keyed by name, a third namespace with the same reserved names.
+	RecordActions map[string]pact.AdminRecordAction
 
 	// scripts and styles are the controller's declared plugin JS and CSS,
 	// in declared order.

modules/cabana/crud.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"git.golem15.com/golem15/summercms/modules/bouncer"
 	"git.golem15.com/golem15/summercms/modules/lagoon"
 	"git.golem15.com/golem15/summercms/modules/pact"
 	"git.golem15.com/golem15/summercms/modules/phrasebook"
@@ -346,6 +347,7 @@ func (s CRUDService) ShowRecord(ctx context.Context, cc *CompiledController, id
 	if ctx == nil {
 		ctx = context.Background()
 	}
+	ctx = towel.WithLocale(ctx, schemaLocale(ctx, s.tr))
 	var result RecordResult
 	err := s.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		tx = tx.WithContext(ctx)
@@ -361,6 +363,10 @@ func (s CRUDService) ShowRecord(ctx context.Context, cc *CompiledController, id
 			return err
 		}
 		result, err = projectFullRecord(ctx, tx, cc, target)
+		if err != nil {
+			return err
+		}
+		result.Meta.Actions, err = s.offeredRecordActions(withTx(ctx, tx), cc, target)
 		return err
 	})
 	if err != nil {
@@ -369,6 +375,102 @@ func (s CRUDService) ShowRecord(ctx context.Context, cc *CompiledController, id
 	return result, nil
 }
 
+// offeredRecordActions lists the declared record actions the principal on ctx
+// may run and that apply to the loaded record, in declared order, with
+// localized label and confirm text (D-10). It is nil when none is offered.
+// Applies runs with the read transaction on ctx; its error fails the read.
+func (s CRUDService) offeredRecordActions(ctx context.Context, cc *CompiledController, record any) ([]RecordAction, error) {
+	if cc == nil || cc.Form == nil || len(cc.Form.recordActions) == 0 {
+		return nil, nil
+	}
+	principal, _ := bouncer.User(ctx)
+	var out []RecordAction
+	for _, name := range cc.Form.recordActions {
+		action, ok := cc.RecordActions[name]
+		if !ok || !Allows(principal, action.Permissions) {
+			continue
+		}
+		if action.Applies != nil {
+			applies, err := action.Applies(ctx, record)
+			if err != nil {
+				return nil, actionFailure(cc, "record action", name, err)
+			}
+			if !applies {
+				continue
+			}
+		}
+		out = append(out, RecordAction{
+			Name:    name,
+			Label:   translateKey(ctx, s.tr, action.Label),
+			Confirm: translateKey(ctx, s.tr, action.Confirm),
+		})
+	}
+	return out, nil
+}
+
+// RecordAction runs the declared record action name on one record in a
+// transaction. The record is loaded through the controller's FormExtendQuery
+// scope with a row lock: a missing or out-of-scope id is not found. The
+// action's Applies is checked again inside the transaction, and an action
+// that does not apply to the record's current state conflicts. A name the
+// form does not declare, or the controller does not register, is not found.
+func (s CRUDService) RecordAction(ctx context.Context, cc *CompiledController, id any, name string) (AdminActionResult, error) {
+	if s.DB == nil {
+		return AdminActionResult{}, errors.New("cabana: database is not configured")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	action, ok := recordActionOf(cc, name)
+	if !ok {
+		return AdminActionResult{}, recordNotFound{}
+	}
+	if _, err := newWritableModel(cc); err != nil {
+		return AdminActionResult{}, err
+	}
+	ctx = towel.WithLocale(ctx, schemaLocale(ctx, s.tr))
+	result := AdminActionResult{Fill: map[string]any{}}
+	err := lagoon.Transaction(ctx, s.DB, func(ctx context.Context, tx *gorm.DB) error {
+		ctx = withTx(ctx, tx)
+		target, err := newWritableModel(cc)
+		if err != nil {
+			return err
+		}
+		pk, err := coercePK(target, id)
+		if err != nil {
+			return err
+		}
+		if err := loadRecord(ctx, tx, cc, target, pk); err != nil {
+			return err
+		}
+		if action.Applies != nil {
+			applies, err := action.Applies(ctx, target)
+			if err != nil {
+				return actionFailure(cc, "record action", name, err)
+			}
+			if !applies {
+				return actionConflict{}
+			}
+		}
+		out, err := action.Run(ctx, pact.AdminRecordActionInput{RecordID: uint64(pkUint(target)), Record: target})
+		if err != nil {
+			return actionFailure(cc, "record action", name, err)
+		}
+		result.Message = translateKey(ctx, s.tr, out.Message)
+		return nil
+	})
+	if err != nil {
+		return AdminActionResult{}, err
+	}
+	return result, nil
+}
+
+// actionConflict is a record action that does not apply to the record's
+// current state (409).
+type actionConflict struct{}
+
+func (actionConflict) Error() string { return "cabana: action does not apply" }
+
 // projectFullRecord is the D-18 record shape: scalar writable fields, relation
 // values keyed by field name, and their labels.
 func projectFullRecord(ctx context.Context, tx *gorm.DB, cc *CompiledController, model any) (RecordResult, error) {
@@ -513,6 +615,11 @@ func writeCRUDError(w http.ResponseWriter, err error) {
 		WriteError(w, http.StatusConflict, "conflict", "Conflict")
 		return
 	}
+	var stale actionConflict
+	if errors.As(err, &stale) {
+		WriteError(w, http.StatusConflict, "conflict", "Conflict")
+		return
+	}
 	WriteError(w, http.StatusInternalServerError, "error", msgServerError)
 }
 
@@ -598,6 +705,10 @@ func lifecycleFailure(cc *CompiledController, err error) error {
 	if errors.As(err, &partial) {
 		return err
 	}
+	var stale actionConflict
+	if errors.As(err, &stale) {
+		return err
+	}
 	var life *lifecycleError
 	if errors.As(err, &life) {
 		return err

modules/cabana/example_actions_test.go

@@ -14,6 +14,7 @@ type Person struct {
 	Name   string `gorm:"column:name"`
 	Email  string `gorm:"column:email"`
 	Active bool   `gorm:"column:active"`
+	Banned bool   `gorm:"column:banned"`
 }
 
 func (Person) TableName() string { return "acme_roster_people" }
@@ -21,13 +22,14 @@ func (Person) TableName() string { return "acme_roster_people" }
 // Fillable lists the columns the admin form may write.
 func (Person) Fillable() []string { return []string{"name", "email"} }
 
-// PeopleController is an admin controller whose list offers bulk actions.
+// PeopleController is an admin controller with bulk and record actions.
 type PeopleController struct{}
 
 var (
-	_ pact.AdminController     = PeopleController{}
-	_ pact.AdminRecordSource   = PeopleController{}
-	_ pact.HasAdminBulkActions = PeopleController{}
+	_ pact.AdminController       = PeopleController{}
+	_ pact.AdminRecordSource     = PeopleController{}
+	_ pact.HasAdminBulkActions   = PeopleController{}
+	_ pact.HasAdminRecordActions = PeopleController{}
 )
 
 func (PeopleController) ID() string        { return "acme.roster.people" }
@@ -86,3 +88,44 @@ func (PeopleController) AdminBulkActions() []pact.AdminBulkAction {
 		},
 	}}
 }
+
+// AdminRecordActions registers the actions config_form.yaml offers under
+// recordActions. Applies decides whether an action fits the record's current
+// state; Run receives the record loaded and locked through the form scope.
+func (PeopleController) AdminRecordActions() []pact.AdminRecordAction {
+	return []pact.AdminRecordAction{{
+		Name:        "activate",
+		Label:       "acme.roster::lang.people.activate",
+		Permissions: []string{"acme.roster.manage"},
+		Applies: func(_ context.Context, record any) (bool, error) {
+			return !record.(*Person).Active, nil
+		},
+		Run: func(ctx context.Context, in pact.AdminRecordActionInput) (pact.AdminRecordActionResult, error) {
+			tx, ok := cabana.TxFromContext(ctx)
+			if !ok {
+				return pact.AdminRecordActionResult{}, errors.New("no transaction")
+			}
+			if err := tx.Model(in.Record).Update("active", true).Error; err != nil {
+				return pact.AdminRecordActionResult{}, err
+			}
+			return pact.AdminRecordActionResult{Message: "acme.roster::lang.people.activated"}, nil
+		},
+	}, {
+		Name:    "reinstate",
+		Label:   "acme.roster::lang.people.reinstate",
+		Confirm: "acme.roster::lang.people.reinstate_confirm",
+		Applies: func(_ context.Context, record any) (bool, error) {
+			return record.(*Person).Banned, nil
+		},
+		Run: func(ctx context.Context, in pact.AdminRecordActionInput) (pact.AdminRecordActionResult, error) {
+			tx, ok := cabana.TxFromContext(ctx)
+			if !ok {
+				return pact.AdminRecordActionResult{}, errors.New("no transaction")
+			}
+			if err := tx.Model(in.Record).Update("banned", false).Error; err != nil {
+				return pact.AdminRecordActionResult{}, err
+			}
+			return pact.AdminRecordActionResult{}, nil
+		},
+	}}
+}

modules/cabana/extension.go

@@ -72,6 +72,11 @@ func compileExtension(pluginID string, cc *CompiledController, fsys fs.FS) error
 		return fmt.Errorf("cabana: admin controller %s/%s: %w", pluginID, id, err)
 	}
 	cc.BulkActions = bulkActions
+	recordActions, err := compileRecordActions(cc.Controller)
+	if err != nil {
+		return fmt.Errorf("cabana: admin controller %s/%s: %w", pluginID, id, err)
+	}
+	cc.RecordActions = recordActions
 	if err := compileClientAssets(pluginID, cc, fsys); err != nil {
 		return err
 	}
@@ -81,6 +86,21 @@ func compileExtension(pluginID string, cc *CompiledController, fsys fs.FS) error
 	if cc.Form == nil {
 		return nil
 	}
+	// Every recordActions name of config_form.yaml must be a record action
+	// the controller registers, with a label (D-10).
+	formFile := cc.Form.configPath
+	if formFile == "" {
+		formFile = "config_form.yaml"
+	}
+	for _, name := range cc.Form.recordActions {
+		action, ok := recordActions[name]
+		if !ok {
+			return bootErr(pluginID, id, formFile, fmt.Errorf("recordActions: unsupported action %s (want a record action the controller registers)", name))
+		}
+		if strings.TrimSpace(action.Label) == "" {
+			return bootErr(pluginID, id, formFile, fmt.Errorf("recordActions: action %s needs a label", name))
+		}
+	}
 	file := cc.Form.fieldsPath
 	if file == "" {
 		file = "fields.yaml"
@@ -308,3 +328,29 @@ func compileBulkActions(ctl pact.AdminController) (map[string]pact.AdminBulkActi
 	}
 	return out, nil
 }
+
+// compileRecordActions collects a controller's registered record actions into
+// their own namespace; create and delete stay reserved.
+func compileRecordActions(ctl pact.AdminController) (map[string]pact.AdminRecordAction, error) {
+	out := map[string]pact.AdminRecordAction{}
+	src, ok := ctl.(pact.HasAdminRecordActions)
+	if !ok || src == nil {
+		return out, nil
+	}
+	for _, action := range src.AdminRecordActions() {
+		if !identifier(action.Name) {
+			return nil, fmt.Errorf("record action name %q is not an identifier", action.Name)
+		}
+		if builtinToolbarActions[action.Name] {
+			return nil, fmt.Errorf("record action %s uses a reserved built-in name (create, delete)", action.Name)
+		}
+		if _, dup := out[action.Name]; dup {
+			return nil, fmt.Errorf("duplicate record action %s", action.Name)
+		}
+		if action.Run == nil {
+			return nil, fmt.Errorf("record action %s has no Run function", action.Name)
+		}
+		out[action.Name] = action
+	}
+	return out, nil
+}

modules/cabana/form_schema.go

@@ -54,6 +54,24 @@ type formConfigDocument struct {
 	Create          *formRedirects   `yaml:"create"`
 	Update          *formRedirects   `yaml:"update"`
 	Messages        *formMessageKeys `yaml:"messages"`
+	RecordActions   recordActionList `yaml:"recordActions"`
+}
+
+// recordActionList is the declarative recordActions list (D-10): the names of
+// record actions the controller registers through pact.HasAdminRecordActions,
+// in display order. Decode has no controller, so membership is resolved in
+// compileExtension.
+type recordActionList struct {
+	items []string
+}
+
+func (l *recordActionList) UnmarshalYAML(node ast.Node) error {
+	items, err := actionNameList(node, "recordActions", "recordActions must be a list of record action names the controller registers")
+	if err != nil {
+		return err
+	}
+	l.items = items
+	return nil
 }
 
 type formRedirects struct {
@@ -118,6 +136,9 @@ func CompileForm(pluginID string, ctl pact.AdminController, fsys fs.FS) (*FormSc
 		Fields:     fields,
 		redirects:  FormRedirects{Default: doc.DefaultRedirect},
 		fieldsPath: fieldsPath,
+		configPath: cfgPath,
+
+		recordActions: doc.RecordActions.items,
 	}
 	if doc.Messages != nil {
 		schema.messageKeys = *doc.Messages

modules/cabana/http.go

@@ -276,6 +276,11 @@ func (s *service) mount(r pact.Router) {
 		constrainController(g)
 		g.Delete("/{vendor}/{plugin}/{controller}/{id}", requireAjax(s.deleteRecord))
 		constrainController(g)
+		// Declared record actions (D-10): the record is loaded through the
+		// form scope before plugin code runs.
+		g.Post("/{vendor}/{plugin}/{controller}/{id}/actions/{action}", requireAjax(s.recordAction))
+		constrainController(g)
+		g.Where("action", "[A-Za-z_][A-Za-z0-9_]*")
 		// Six-segment GET routes share one pattern: ServeMux rejects the
 		// relation list next to the field options route (neither is more
 		// specific), so nestedGet dispatches on the literal segments.

modules/cabana/openapi_conformance_test.go

@@ -279,6 +279,18 @@ func TestPhase10OpenAPIConformance(t *testing.T) {
 			spare := e.send(t, http.MethodPost, "/acme/conform/gadgets", map[string]any{"name": "spare-" + e.stamp}, true)
 			return e.send(t, http.MethodPost, "/acme/conform/gadgets/bulk-delete", map[string]any{"ids": []uint{dataID(t, spare.Body.Bytes())}}, true)
 		}, into[cabana.Envelope[cabana.BulkResult]](), nil},
+		{"POST /{vendor}/{plugin}/{controller}/{id}/actions/{action}", 200, "cabana.Envelope-cabana_AdminActionResult", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
+			shown := e.send(t, http.MethodGet, fmt.Sprintf("/acme/conform/gadgets/%d", e.gadgetID), nil, true)
+			if !strings.Contains(shown.Body.String(), `"actions":[{"name":"ping","label":"Ping"}]`) {
+				t.Fatalf("show does not offer the record action: %s", shown.Body.String())
+			}
+			rec := e.send(t, http.MethodPost, fmt.Sprintf("/acme/conform/gadgets/%d/actions/ping", e.gadgetID), map[string]any{}, true)
+			var body cabana.Envelope[cabana.AdminActionResult]
+			if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || body.Data.Message != "Pinged" || body.Data.Fill == nil || len(body.Data.Fill) != 0 {
+				t.Fatalf("record action body = %s (%v)", rec.Body.String(), err)
+			}
+			return rec
+		}, into[cabana.Envelope[cabana.AdminActionResult]](), nil},
 		{"POST /{vendor}/{plugin}/{controller}/bulk/{action}", 200, "cabana.Envelope-cabana_BulkActionResult", func(t *testing.T, e *conformEnv) *httptest.ResponseRecorder {
 			rec := e.send(t, http.MethodPost, "/acme/conform/gadgets/bulk/touch", map[string]any{"ids": []uint{e.gadgetID}}, true)
 			var body cabana.Envelope[cabana.BulkActionResult]
@@ -808,6 +820,17 @@ func (conformController) AdminBulkActions() []pact.AdminBulkAction {
 		},
 	}}
 }
+
+// AdminRecordActions registers the record action the form's recordActions
+// declares.
+func (conformController) AdminRecordActions() []pact.AdminRecordAction {
+	return []pact.AdminRecordAction{{
+		Name: "ping", Label: "Ping", Permissions: []string{"acme.conform.access"},
+		Run: func(context.Context, pact.AdminRecordActionInput) (pact.AdminRecordActionResult, error) {
+			return pact.AdminRecordActionResult{Message: "Pinged"}, nil
+		},
+	}}
+}
 func (conformController) AdminJS() []string { return []string{"assets/js/lookup.js"} }
 
 // PartialData supplies curated view models, never the gadget model itself.
@@ -892,6 +915,7 @@ create:
 update:
     redirect: acme/conform/gadgets
     redirectClose: acme/conform/gadgets
+recordActions: [ping]
 `),
 		"controllers/gadgets/config_relation.yaml": file(`members:
     label: Members

modules/cabana/phase10_coverage_test.go

@@ -99,6 +99,7 @@ func TestPhase10Coverage(t *testing.T) {
 			"POST /{vendor}/{plugin}/{controller}/bulk/{action}",
 			"POST /{vendor}/{plugin}/{controller}/toolbar/{action}",
 			"POST /{vendor}/{plugin}/{controller}/widgets/{field}",
+			"POST /{vendor}/{plugin}/{controller}/{id}/actions/{action}",
 			"POST /{vendor}/{plugin}/{controller}/{id}/files/{field}",
 			"POST /{vendor}/{plugin}/{controller}/{id}/files/{field}/reorder",
 			"POST /{vendor}/{plugin}/{controller}/{id}/relations/{name}/delete",
@@ -115,7 +116,7 @@ func TestPhase10Coverage(t *testing.T) {
 			"PUT /{vendor}/{plugin}/{controller}/{id}/relations/{name}/records/{child}/files/{field}/{file}",
 		}
 		if strings.Join(unsafe, "\n") != strings.Join(want, "\n") {
-			t.Fatalf("unsafe routes changed; extend TestPhase10CSRF (it expects 24 besides login):\n%s", strings.Join(unsafe, "\n"))
+			t.Fatalf("unsafe routes changed; extend TestPhase10CSRF (it expects 25 besides login):\n%s", strings.Join(unsafe, "\n"))
 		}
 		// The routes added in Phase 10 are safe reads: GET /lang and the shared
 		// nested pattern serving field options, filter options and relation lists.

modules/cabana/phase10_csrf_test.go

@@ -67,12 +67,13 @@ func TestPhase10CSRF(t *testing.T) {
 		})
 	}
 	// refresh, logout, settings put, create, bulk-delete, bulk action,
-	// widget action, toolbar action, update, delete, link, unlink, file
+	// widget action, toolbar action, update, delete, record action, link,
+	// unlink, file
 	// upload, file reorder, file caption, file remove, relation child
 	// create, update and delete, pivot update, child file upload, reorder,
 	// caption and remove
-	if unsafe != 24 {
-		t.Fatalf("walked %d state-changing routes, want 24: %v", unsafe, router.order)
+	if unsafe != 25 {
+		t.Fatalf("walked %d state-changing routes, want 25: %v", unsafe, router.order)
 	}
 
 	loginHandler := router.handlers[login]

modules/cabana/phase121_actions_test.go

@@ -12,7 +12,10 @@ import (
 	"testing"
 	"testing/fstest"
 
+	"git.golem15.com/golem15/summercms/modules/backpack"
 	"git.golem15.com/golem15/summercms/modules/cabana"
+	"git.golem15.com/golem15/summercms/modules/compass"
+	"git.golem15.com/golem15/summercms/modules/party"
 )
 
 const rosterPeople = "/acme/roster/people"
@@ -249,3 +252,205 @@ func TestListSchemaBulkActionsBoot(t *testing.T) {
 		}
 	})
 }
+
+// rosterOffered returns the record action names the show response offers.
+func rosterOffered(t *testing.T, env *rosterEnv, id uint, auth string) []string {
+	t.Helper()
+	rec := env.expect(t, http.StatusOK, http.MethodGet, fmt.Sprintf("%s/%d", rosterPeople, id), "", auth)
+	var body cabana.RecordEnvelope
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("show body %s: %v", rec.Body.String(), err)
+	}
+	names := []string{}
+	for _, action := range body.Meta.Actions {
+		names = append(names, action.Name)
+	}
+	return names
+}
+
+// TestRecordActionSmoke drives a declared record action through the assembled
+// router on PostgreSQL (D-10; T-12.1-02, T-12.1-03, T-12.1-04): the offered
+// actions of a shown record, the form scope, Applies inside the transaction,
+// the action permission, the strict body and the CSRF header.
+func TestRecordActionSmoke(t *testing.T) {
+	env, gdb := newRosterEnv(t)
+	idle := rosterInsert(t, gdb, rosterPerson{Tenant: "acme", Name: "Idle", Email: "idle@example.test"})
+	banned := rosterInsert(t, gdb, rosterPerson{Tenant: "acme", Name: "Banned", Active: true, Banned: true})
+	foreign := rosterInsert(t, gdb, rosterPerson{Tenant: "other", Name: "Zed"})
+	action := func(id uint, name string) string {
+		return fmt.Sprintf("%s/%d/actions/%s", rosterPeople, id, name)
+	}
+
+	t.Run("show offers the permitted actions that apply", func(t *testing.T) {
+		if got := rosterOffered(t, env, idle, "bearer"); !reflect.DeepEqual(got, []string{"activate"}) {
+			t.Fatalf("idle person, full admin: %v", got)
+		}
+		if got := rosterOffered(t, env, banned, "bearer"); !reflect.DeepEqual(got, []string{"reinstate"}) {
+			t.Fatalf("banned person, full admin: %v", got)
+		}
+		// The limited admin lacks acme.roster.manage: no activate.
+		if got := rosterOffered(t, env, idle, "limited"); len(got) != 0 {
+			t.Fatalf("idle person, limited admin: %v", got)
+		}
+		rec := env.expect(t, http.StatusOK, http.MethodGet, fmt.Sprintf("%s/%d", rosterPeople, banned), "", "bearer")
+		if !strings.Contains(rec.Body.String(), `"actions":[{"name":"reinstate","label":"Reinstate","confirm":"Lift the ban on this person?"}]`) {
+			t.Fatalf("offered action is not localized: %s", rec.Body.String())
+		}
+		// A record with no offered action has no actions key at all.
+		rec = env.expect(t, http.StatusOK, http.MethodGet, fmt.Sprintf("%s/%d", rosterPeople, idle), "", "limited")
+		if strings.Contains(rec.Body.String(), `"actions"`) {
+			t.Fatalf("meta.actions sent without an offered action: %s", rec.Body.String())
+		}
+	})
+
+	t.Run("create and update responses carry no actions", func(t *testing.T) {
+		rec := env.expect(t, http.StatusCreated, http.MethodPost, rosterPeople, `{"name":"Fresh"}`, "bearer")
+		if strings.Contains(rec.Body.String(), `"actions"`) {
+			t.Fatalf("create response: %s", rec.Body.String())
+		}
+		rec = env.expect(t, http.StatusOK, http.MethodPut, fmt.Sprintf("%s/%d", rosterPeople, idle), `{"name":"Idle"}`, "bearer")
+		if strings.Contains(rec.Body.String(), `"actions"`) {
+			t.Fatalf("update response: %s", rec.Body.String())
+		}
+	})
+
+	t.Run("a controller without record actions sends no actions key", func(t *testing.T) {
+		demo, demoDB := newActEnv(t)
+		gadget := actInsert(t, demoDB, "plain", "acme")
+		rec := demo.expect(t, http.StatusOK, http.MethodGet, fmt.Sprintf("/acme/demo/gadgets/%d", gadget), "", "bearer")
+		if strings.Contains(rec.Body.String(), `"actions"`) || !strings.Contains(rec.Body.String(), `"labels"`) {
+			t.Fatalf("show = %s", rec.Body.String())
+		}
+	})
+
+	t.Run("limited admin is refused", func(t *testing.T) {
+		rec := env.expect(t, http.StatusForbidden, http.MethodPost, action(idle, "activate"), `{}`, "limited")
+		actErrorCode(t, rec.Body.Bytes(), "forbidden")
+		if rosterLoad(t, gdb, idle).Active {
+			t.Fatal("a denied admin changed the record")
+		}
+	})
+
+	t.Run("cookie POSTs need X-Requested-With", func(t *testing.T) {
+		rec := env.expect(t, http.StatusForbidden, http.MethodPost, action(idle, "activate"), `{}`, "cookie-only")
+		actErrorCode(t, rec.Body.Bytes(), "forbidden")
+		if rosterLoad(t, gdb, idle).Active {
+			t.Fatal("a request without the CSRF header changed the record")
+		}
+	})
+
+	t.Run("strict body", func(t *testing.T) {
+		for _, body := range []string{fmt.Sprintf(`{"record_id":%d}`, idle), `{"values":{}}`, `{"extra":1}`, `{} {}`, ``} {
+			rec := env.expect(t, http.StatusUnprocessableEntity, http.MethodPost, action(idle, "activate"), body, "bearer")
+			actErrorCode(t, rec.Body.Bytes(), "validation_failed")
+		}
+		if rosterLoad(t, gdb, idle).Active {
+			t.Fatal("a malformed body changed the record")
+		}
+	})
+
+	t.Run("out-of-scope and missing records are 404", func(t *testing.T) {
+		for _, id := range []uint{foreign, 999999} {
+			env.expect(t, http.StatusNotFound, http.MethodPost, action(id, "activate"), `{}`, "bearer")
+		}
+		if rosterLoad(t, gdb, foreign).Active {
+			t.Fatal("an out-of-scope record was activated")
+		}
+	})
+
+	t.Run("undeclared and reserved names are 404", func(t *testing.T) {
+		for _, name := range []string{"missing", "archive", "delete", "create"} {
+			env.expect(t, http.StatusNotFound, http.MethodPost, action(idle, name), `{}`, "bearer")
+		}
+	})
+
+	if calls := env.spy.takeRecord(); len(calls) != 0 {
+		t.Fatalf("a refused request reached the plugin: %+v", calls)
+	}
+
+	t.Run("runs once, then no longer applies", func(t *testing.T) {
+		rec := env.expect(t, http.StatusOK, http.MethodPost, action(idle, "activate"), `{}`, "bearer")
+		result := actResult(t, rec)
+		if result.Message != "The person was activated." || result.Fill == nil || len(result.Fill) != 0 {
+			t.Fatalf("result = %+v", result)
+		}
+		if !rosterLoad(t, gdb, idle).Active {
+			t.Fatal("the record was not activated")
+		}
+		calls := env.spy.takeRecord()
+		person, ok := calls[0].Record.(*rosterPerson)
+		if len(calls) != 1 || calls[0].RecordID != uint64(idle) || !ok || person.ID != idle || person.Tenant != "acme" {
+			t.Fatalf("input = %+v", calls)
+		}
+		// Applies is checked again inside the transaction.
+		rec = env.expect(t, http.StatusConflict, http.MethodPost, action(idle, "activate"), `{}`, "bearer")
+		actErrorCode(t, rec.Body.Bytes(), "conflict")
+		if calls := env.spy.takeRecord(); len(calls) != 0 {
+			t.Fatalf("the action ran for a record it does not apply to: %+v", calls)
+		}
+		if got := rosterOffered(t, env, idle, "bearer"); len(got) != 0 {
+			t.Fatalf("offered after the run: %v", got)
+		}
+	})
+
+	t.Run("an action without its own permission runs for the limited admin", func(t *testing.T) {
+		rec := env.expect(t, http.StatusOK, http.MethodPost, action(banned, "reinstate"), `{}`, "limited")
+		if result := actResult(t, rec); result.Message != "" {
+			t.Fatalf("result = %+v", result)
+		}
+		if rosterLoad(t, gdb, banned).Banned {
+			t.Fatal("the ban was not lifted")
+		}
+		env.spy.takeRecord()
+	})
+}
+
+// TestFormSchemaRecordActionsBoot checks the fail-loud compile of the
+// recordActions key (D-10).
+func TestFormSchemaRecordActionsBoot(t *testing.T) {
+	fields, err := os.ReadFile(filepath.Join(rosterDir, "models/person/fields.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	const head = "form: ~/plugins/acme/roster/models/person/fields.yaml\nmodelClass: Person\n"
+	for _, tc := range []struct {
+		name, yaml, want string
+	}{
+		{"duplicate", head + "recordActions: [activate, activate]\n", "recordActions: duplicate action activate"},
+		{"scalar", head + "recordActions: activate\n", "recordActions must be a list of record action names the controller registers"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			fsys := fstest.MapFS{
+				"controllers/people/config_form.yaml": &fstest.MapFile{Data: []byte(tc.yaml)},
+				"models/person/fields.yaml":           &fstest.MapFile{Data: fields},
+			}
+			_, err := cabana.CompileForm("acme.roster", rosterController{}, fsys)
+			if err == nil || !strings.Contains(err.Error(), tc.want) || !strings.Contains(err.Error(), "controllers/people/config_form.yaml") {
+				t.Fatalf("error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+
+	// A name the controller does not register is refused when the controller
+	// is activated, where the form meets its registered actions.
+	t.Run("unregistered", func(t *testing.T) {
+		fsys := fstest.MapFS{}
+		for _, name := range []string{"controllers/people/config_list.yaml", "models/person/columns.yaml", "models/person/fields.yaml"} {
+			data, err := os.ReadFile(filepath.Join(rosterDir, name))
+			if err != nil {
+				t.Fatal(err)
+			}
+			fsys[name] = &fstest.MapFile{Data: data}
+		}
+		fsys["controllers/people/config_form.yaml"] = &fstest.MapFile{Data: []byte(head + "recordActions: [activate, promote]\n")}
+		cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{"SUMMER_ENV=development", "SUMMER_ADMIN__JWT__SECRET=" + adminTestSecret}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, err = cabana.Activate(backpack.New(cfg), []party.Plugin{rosterPlugin{spy: &rosterSpy{}, fsys: fsys}})
+		const want = "recordActions: unsupported action promote (want a record action the controller registers)"
+		if err == nil || !strings.Contains(err.Error(), want) || !strings.Contains(err.Error(), "acme.roster.people") || !strings.Contains(err.Error(), "controllers/people/config_form.yaml") {
+			t.Fatalf("error = %v, want %q", err, want)
+		}
+	})
+}

modules/cabana/phase121_fixture_test.go

@@ -46,8 +46,23 @@ func (rosterPerson) Rules() map[string]string { return map[string]string{"name":
 
 // rosterSpy records what each registered action's Run receives.
 type rosterSpy struct {
-	mu   sync.Mutex
-	bulk []pact.AdminBulkActionInput
+	mu     sync.Mutex
+	bulk   []pact.AdminBulkActionInput
+	record []pact.AdminRecordActionInput
+}
+
+func (s *rosterSpy) recordOne(in pact.AdminRecordActionInput) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.record = append(s.record, in)
+}
+
+func (s *rosterSpy) takeRecord() []pact.AdminRecordActionInput {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := s.record
+	s.record = nil
+	return out
 }
 
 func (s *rosterSpy) recordBulk(in pact.AdminBulkActionInput) {
@@ -64,7 +79,12 @@ func (s *rosterSpy) takeBulk() []pact.AdminBulkActionInput {
 	return out
 }
 
-type rosterPlugin struct{ spy *rosterSpy }
+// rosterPlugin is the acme.roster fixture plugin. fsys, when set, replaces
+// the fixture tree (boot-error tests).
+type rosterPlugin struct {
+	spy  *rosterSpy
+	fsys fs.FS
+}
 
 func (rosterPlugin) ID() string                   { return "acme.roster" }
 func (rosterPlugin) Requires() []string           { return nil }
@@ -76,7 +96,12 @@ func (p rosterPlugin) AdminControllers() []pact.AdminController {
 func (rosterPlugin) Permissions() []pact.Permission {
 	return []pact.Permission{{Code: "acme.roster.access", Roles: []string{"developer"}}, {Code: "acme.roster.manage", Roles: []string{"developer"}}}
 }
-func (rosterPlugin) AdminFS() fs.FS { return os.DirFS(rosterDir) }
+func (p rosterPlugin) AdminFS() fs.FS {
+	if p.fsys != nil {
+		return p.fsys
+	}
+	return os.DirFS(rosterDir)
+}
 
 // LangFS serves only the fixture's lang/ tree.
 func (rosterPlugin) LangFS() fs.FS {
@@ -153,6 +178,46 @@ func (c rosterController) AdminBulkActions() []pact.AdminBulkAction {
 	}}
 }
 
+// AdminRecordActions: activate needs acme.roster.manage and applies to a
+// person who is not active; reinstate applies to a banned person and lifts
+// the ban.
+func (c rosterController) AdminRecordActions() []pact.AdminRecordAction {
+	return []pact.AdminRecordAction{{
+		Name: "activate", Label: "acme.roster::lang.people.activate",
+		Permissions: []string{"acme.roster.manage"},
+		Applies: func(_ context.Context, record any) (bool, error) {
+			return !record.(*rosterPerson).Active, nil
+		},
+		Run: func(ctx context.Context, in pact.AdminRecordActionInput) (pact.AdminRecordActionResult, error) {
+			c.spy.recordOne(in)
+			tx, ok := cabana.TxFromContext(ctx)
+			if !ok {
+				return pact.AdminRecordActionResult{}, fmt.Errorf("no transaction on the context")
+			}
+			if err := tx.Model(in.Record).Update("active", true).Error; err != nil {
+				return pact.AdminRecordActionResult{}, err
+			}
+			return pact.AdminRecordActionResult{Message: "acme.roster::lang.people.activated"}, nil
+		},
+	}, {
+		Name: "reinstate", Label: "acme.roster::lang.people.reinstate", Confirm: "acme.roster::lang.people.reinstate_confirm",
+		Applies: func(_ context.Context, record any) (bool, error) {
+			return record.(*rosterPerson).Banned, nil
+		},
+		Run: func(ctx context.Context, in pact.AdminRecordActionInput) (pact.AdminRecordActionResult, error) {
+			c.spy.recordOne(in)
+			tx, ok := cabana.TxFromContext(ctx)
+			if !ok {
+				return pact.AdminRecordActionResult{}, fmt.Errorf("no transaction on the context")
+			}
+			if err := tx.Model(in.Record).Update("banned", false).Error; err != nil {
+				return pact.AdminRecordActionResult{}, err
+			}
+			return pact.AdminRecordActionResult{}, nil
+		},
+	}}
+}
+
 // rosterEnv is the assembled admin API over the roster fixture. The embedded
 // actEnv supplies call and expect with the four auth modes: bearer (developer
 // token), limited (acme.roster.access only), cookie and cookie-only.

modules/cabana/registry.go

@@ -232,6 +232,11 @@ func compileContributions(reg *Registry, plugins []party.Plugin) error {
 				return err
 			}
 		}
+		for name, action := range controller.RecordActions {
+			if err := reg.validatePermissions("record action "+id+"."+name, action.Permissions); err != nil {
+				return err
+			}
+		}
 	}
 	for _, item := range reg.navigation {
 		if err := reg.validateNavigation(item); err != nil {

modules/cabana/relation_field.go

@@ -55,9 +55,13 @@ type RelationOption struct {
 }
 
 // RecordMeta is the record envelope meta: display labels per relation field,
-// in the same order as the ids in data.
+// in the same order as the ids in data. Actions are the declared record
+// actions the requesting admin may run and that apply to the record, in
+// declared order; only the show response fills it, and it is omitted when no
+// action is offered.
 type RecordMeta struct {
-	Labels map[string][]RelationOption `json:"labels"`
+	Labels  map[string][]RelationOption `json:"labels"`
+	Actions []RecordAction              `json:"actions,omitempty"`
 }
 
 // RecordEnvelope is the show, create and update response.

modules/cabana/schema_types.go

@@ -136,6 +136,10 @@ type FormSchema struct {
 	redirects   FormRedirects
 	// fieldsPath is the fields.yaml the form was compiled from, for boot errors.
 	fieldsPath string
+	// configPath is the config_form.yaml the form was compiled from.
+	configPath string
+	// recordActions are the declared recordActions names, in declared order.
+	recordActions []string
 }
 
 // FormView is one request's localized form, including the locale actually used.
@@ -181,6 +185,15 @@ type ToolbarAction struct {
 	Label string `json:"label"`
 }
 
+// RecordAction is one record action offered for a shown record (D-10): the
+// name posted to .../{id}/actions/{action}, its localized label and its own
+// confirmation question, empty when the admin should show its default text.
+type RecordAction struct {
+	Name    string `json:"name"`
+	Label   string `json:"label"`
+	Confirm string `json:"confirm,omitempty"`
+}
+
 // FormRedirects are config_form.yaml defaultRedirect, create.* and update.*.
 type FormRedirects struct {
 	Default string       `json:"default"`

modules/cabana/security_coverage_test.go

@@ -59,6 +59,7 @@ var phase09Routes = []adminRoute{
 	{key: "GET /{vendor}/{plugin}/{controller}/{id}"},
 	{key: "PUT /{vendor}/{plugin}/{controller}/{id}"},
 	{key: "DELETE /{vendor}/{plugin}/{controller}/{id}"},
+	{key: "POST /{vendor}/{plugin}/{controller}/{id}/actions/{action}"},
 	{key: "GET /{vendor}/{plugin}/{controller}/{id}/relations/{name}", mounted: nestedGetRoute},
 	{key: "GET /{vendor}/{plugin}/{controller}/{id}/relations/{name}/candidates"},
 	{key: "POST /{vendor}/{plugin}/{controller}/{id}/relations/{name}/link"},
@@ -292,6 +293,7 @@ func phase09ProtectedCalls() []phase09Call {
 		{"create", (*service).create},
 		{"bulk-delete", (*service).bulkDelete},
 		{"bulk-action", (*service).bulkAction},
+		{"record-action", (*service).recordAction},
 		{"widget-action", (*service).widgetAction},
 		{"toolbar-action", (*service).toolbarAction},
 		{"partial", (*service).partial},

modules/cabana/testdata/roster/controllers/people/config_form.yaml

@@ -8,3 +8,4 @@ create:
 update:
     redirect: acme/roster/people
     redirectClose: acme/roster/people
+recordActions: [activate, reinstate]

modules/cabana/testdata/roster/lang/en/lang.yaml

@@ -8,3 +8,6 @@ people:
   activate_confirm: Activate the selected people?
   archive: Archive
   archived: The selected people were archived.
+  activated: The person was activated.
+  reinstate: Reinstate
+  reinstate_confirm: Lift the ban on this person?

modules/cabana/testdata/roster/lang/pl/lang.yaml

@@ -8,3 +8,6 @@ people:
   activate_confirm: Aktywować zaznaczone osoby?
   archive: Archiwizuj
   archived: Zaznaczone osoby zostały zarchiwizowane.
+  activated: Osoba została aktywowana.
+  reinstate: Przywróć
+  reinstate_confirm: Zdjąć blokadę z tej osoby?

modules/pact/README.md

@@ -14,7 +14,7 @@ Capability interfaces that compiled plugins implement to contribute routes, conf
 - HTTP contracts: the `pact.Router` group builder (implemented by surf), the `pact.Middleware` type, and named, parameterized (`name:param`) and house-envelope middleware through `pact.HasMiddleware`, `pact.HasMiddlewareFactories` and `pact.HasHouseMiddleware`.
 - Backend registration data: `pact.Permission`, `pact.NavigationItem` and `pact.SettingsItem`, exposed through `pact.HasPermissions`, `pact.HasNavigation` and `pact.HasSettings`.
 - Admin controller contracts: `pact.AdminController`, `pact.HasAdminControllers`, `pact.AdminAssets` (embedded Winter-shaped admin YAML), `pact.AdminPermissioned` and `pact.AdminRecordSource`.
-- Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: `pact.AdminClientAssets` (per-controller JS and CSS from the plugin's embedded `assets/` tree, Winter's `addJs`/`addCss`), `pact.HasAdminActions` with `pact.AdminAction`, `pact.AdminActionInput` and `pact.AdminActionResult` (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), `pact.HasAdminBulkActions` with `pact.AdminBulkAction`, `pact.AdminBulkActionInput` and `pact.AdminBulkActionResult` (named actions on the rows selected in a list, which receive records the framework loaded through the list scope, never ids), and `pact.AdminPartialData` (the curated view model a partial template renders).
+- Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: `pact.AdminClientAssets` (per-controller JS and CSS from the plugin's embedded `assets/` tree, Winter's `addJs`/`addCss`), `pact.HasAdminActions` with `pact.AdminAction`, `pact.AdminActionInput` and `pact.AdminActionResult` (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), `pact.HasAdminBulkActions` with `pact.AdminBulkAction`, `pact.AdminBulkActionInput` and `pact.AdminBulkActionResult` (named actions on the rows selected in a list, which receive records the framework loaded through the list scope, never ids), `pact.HasAdminRecordActions` with `pact.AdminRecordAction`, `pact.AdminRecordActionInput` and `pact.AdminRecordActionResult` (named actions on one record, each with an `Applies` rule for the record's state), and `pact.AdminPartialData` (the curated view model a partial template renders).
 - Optional admin hooks a controller or model can implement: list and form query scoping (`pact.ListExtendQuery`, `pact.FormExtendQuery`), create, update and delete hooks (`pact.FormBeforeCreate`, `pact.FormAfterUpdate`, `pact.FormBeforeDelete` and their siblings), relation hooks (`pact.RelationExtendManageQuery`, `pact.RelationExtendOptionsQuery`, `pact.RelationBeforeLink`), relation child hooks around creating, updating and deleting a related record (`pact.RelationBeforeCreate`, `pact.RelationAfterCreate`, `pact.RelationBeforeUpdate`, `pact.RelationAfterUpdate`, `pact.RelationBeforeDelete`, `pact.RelationAfterDelete`), filter scopes (`pact.FilterScope`, `pact.FilterOptions`) and dropdown options (`pact.DropdownOptionsProvider`).
 - A background job contract (`pact.Job`, `pact.JobArgs`) that does not depend on any queue library.
 - A schedule contract: `pact.HasSchedule` returns `pact.ScheduledCommand` entries (a registered command name, its arguments and a `pact.Cadence` built with `pact.Daily`, `pact.DailyAt` or `pact.Every`), the Go form of WinterCMS `registerSchedule`. It does not depend on any queue library either.
@@ -113,6 +113,10 @@ func (p *Plugin) Schedule() []pact.ScheduledCommand {
 | `pact.AdminBulkActionInput` | What a bulk action receives: `Records`, the selected records loaded and row-locked through the list scope. |
 | `pact.AdminBulkActionResult` | What a bulk action returns: an optional message for the toast and `Affected`, the number of records it changed. |
 | `pact.HasAdminBulkActions` | Registers a controller's bulk actions for the `bulkActions` list of `config_list.yaml`. |
+| `pact.AdminRecordAction` | One named record action: name, label, optional confirm text, extra permissions, the optional `Applies` rule and the Go `Run` function. |
+| `pact.AdminRecordActionInput` | What a record action receives: `RecordID` and `Record`, the record loaded and row-locked through the form scope. |
+| `pact.AdminRecordActionResult` | What a record action returns: an optional message for the toast. |
+| `pact.HasAdminRecordActions` | Registers a controller's record actions for the `recordActions` list of `config_form.yaml`. |
 | `pact.AdminPartialData` | Supplies the view model a controller partial template renders; never the GORM model. |
 | `pact.FilterScope` | Model scopes a list filter may call, limited to an exact allow list. |
 | `pact.RelationBeforeLink` | Optional controller hook that checks or fills pivot columns before a relation link is written. |

modules/pact/capabilities.go

@@ -299,6 +299,50 @@ type HasAdminBulkActions interface {
 	AdminBulkActions() []AdminBulkAction
 }
 
+// AdminRecordAction is one controller action an administrator runs on a
+// single record (config_form.yaml recordActions). The admin framework owns the
+// HTTP route, the CSRF check, authentication, the record lookup and the
+// transaction; Run only carries the business logic and reads the write
+// transaction with cabana.TxFromContext. Name is an identifier unique among
+// the controller's record actions; create and delete are reserved, and a bulk
+// action may use the same name. Label and Confirm are phrase keys or literal
+// text; an empty Confirm means the framework's default confirm text.
+// Permissions are checked in addition to the controller's
+// RequiredPermissions. Applies reports whether the action applies to the
+// record in its current state: a nil Applies means the action always applies.
+// Applies must be a pure read, because it also runs when a record is shown, to
+// decide which actions the admin is offered.
+type AdminRecordAction struct {
+	Name        string
+	Label       string
+	Confirm     string
+	Permissions []string
+	Applies     func(ctx context.Context, record any) (bool, error)                                   `json:"-"`
+	Run         func(ctx context.Context, in AdminRecordActionInput) (AdminRecordActionResult, error) `json:"-"`
+}
+
+// AdminRecordActionInput is what the framework hands an AdminRecordAction.
+// Record is the record the framework loaded through the controller's
+// FormExtendQuery scope with a row lock, inside the action's transaction;
+// RecordID is its primary key.
+type AdminRecordActionInput struct {
+	RecordID uint64
+	Record   any
+}
+
+// AdminRecordActionResult is a record action's answer. Message is a phrase key
+// or text, localized by the framework and shown as a toast; when it is empty
+// the admin shows its default text.
+type AdminRecordActionResult struct {
+	Message string
+}
+
+// HasAdminRecordActions is implemented by an admin controller that registers
+// named record actions for its config_form.yaml recordActions list.
+type HasAdminRecordActions interface {
+	AdminRecordActions() []AdminRecordAction
+}
+
 // AdminPartialData supplies the view model a controller partial template
 // renders (config_list.yaml headerPartial, fields.yaml `type: partial`). name
 // is the partial name; record is the scoped record for a form partial on an

modules/phrasebook/backend/lang/en/lang.yaml

@@ -91,6 +91,9 @@ form:
   tab_errors:
     one: ":count error"
     other: ":count errors"
+  action_confirm: "Run “:action” on this record?"
+  action_done: Action completed.
+  action_stale: This action no longer applies to this record. The page has been refreshed.
 relation:
   add: Add
   link: Link

modules/phrasebook/backend/lang/pl/lang.yaml

@@ -101,6 +101,9 @@ form:
     few: ":count błędy"
     many: ":count błędów"
     other: ":count błędu"
+  action_confirm: "Wykonać „:action” na tym rekordzie?"
+  action_done: Akcja została wykonana.
+  action_stale: Ta akcja nie dotyczy już tego rekordu. Strona została odświeżona.
 relation:
   add: Dodaj
   link: Dołącz