pad/internal/models/collection.go

package models

import (
	"encoding/json"
	"errors"
	"time"
)

type FieldDef struct {
	Key             string   `json:"key"`
	Label           string   `json:"label"`
	Type            string   `json:"type"` // text, number, select, multi_select, date, checkbox, url, relation, json
	Options         []string `json:"options,omitempty"`
	TerminalOptions []string `json:"terminal_options,omitempty"` // for select fields: which options represent a terminal/finalized state
	Default         any      `json:"default,omitempty"`
	Required        bool     `json:"required,omitempty"`
	Computed        bool     `json:"computed,omitempty"`
	Collection      string   `json:"collection,omitempty"`   // for relation type
	Suffix          string   `json:"suffix,omitempty"`       // for number type display
	Pattern         string   `json:"pattern,omitempty"`      // optional ECMAScript-style regex applied to text values; empty = no pattern check
	UniqueScope     string   `json:"unique_scope,omitempty"` // "workspace_collection" enforces uniqueness within a collection (non-empty values only); empty = no uniqueness
}

type CollectionSchema struct {
	Fields []FieldDef `json:"fields"`
}

// QuickAction defines a prompt template that can be triggered from the UI.
type QuickAction struct {
	Label  string `json:"label"`          // display label for the button
	Prompt string `json:"prompt"`         // prompt template with {ref}, {title}, {status}, etc.
	Scope  string `json:"scope"`          // "item" or "collection"
	Icon   string `json:"icon,omitempty"` // optional emoji/icon
}

type CollectionSettings struct {
	Layout          string        `json:"layout,omitempty"`       // fields-primary, content-primary, balanced
	DefaultView     string        `json:"default_view,omitempty"` // list, board, table
	BoardGroupBy    string        `json:"board_group_by,omitempty"`
	ListSortBy      string        `json:"list_sort_by,omitempty"`
	ListGroupBy     string        `json:"list_group_by,omitempty"`
	QuickActions    []QuickAction `json:"quick_actions,omitempty"`
	ContentTemplate string        `json:"content_template,omitempty"` // markdown template for new items
}

type Collection struct {
	ID          string `json:"id"`
	WorkspaceID string `json:"workspace_id"`
	Name        string `json:"name"`
	Slug        string `json:"slug"`
	Icon        string `json:"icon"`
	Description string `json:"description"`
	Schema      string `json:"schema"`   // JSON string in DB, parsed via methods
	Settings    string `json:"settings"` // JSON string in DB
	// Traits is the collection's kernel-trait declaration set (SPEC-5), a
	// JSON string in the DB parsed via ParseCollectionTraits. Its own column
	// rather than a key inside Schema on purpose: Schema is overwritten
	// wholesale on update and every client rebuilds it fields-only, so a
	// traits key stored there is destroyed by any ordinary collection edit.
	// See collection_traits.go for the full rationale. TASK-2657.
	Traits    string     `json:"traits"`
	Prefix    string     `json:"prefix"`
	SortOrder int        `json:"sort_order"`
	IsDefault bool       `json:"is_default"`
	IsSystem  bool       `json:"is_system"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	DeletedAt *time.Time `json:"deleted_at,omitempty"`

	// Computed (not stored)
	ItemCount       int `json:"item_count"`
	ActiveItemCount int `json:"active_item_count"`
}

type CollectionCreate struct {
	Name        string `json:"name"`
	Slug        string `json:"slug,omitempty"`
	Prefix      string `json:"prefix,omitempty"`
	Icon        string `json:"icon,omitempty"`
	Description string `json:"description,omitempty"`
	Schema      string `json:"schema,omitempty"`
	Settings    string `json:"settings,omitempty"`
	Traits      string `json:"traits,omitempty"`
	IsDefault   bool   `json:"is_default,omitempty"`
	IsSystem    bool   `json:"is_system,omitempty"`
}

// FieldMigration describes a bulk update to apply to existing items when
// a collection schema changes (e.g. renaming select options).
type FieldMigration struct {
	Field         string            `json:"field"`                    // field key to migrate
	RenameOptions map[string]string `json:"rename_options,omitempty"` // old_value → new_value
}

type CollectionUpdate struct {
	Name        *string `json:"name,omitempty"`
	Prefix      *string `json:"prefix,omitempty"`
	Icon        *string `json:"icon,omitempty"`
	Description *string `json:"description,omitempty"`
	Schema      *string `json:"schema,omitempty"`
	Settings    *string `json:"settings,omitempty"`
	// Traits, when non-nil, replaces the collection's kernel-trait
	// declarations. Nil leaves them untouched — which is the case for every
	// client that rebuilds a collection's schema/settings blobs without
	// knowing traits exist, and is why traits survive an ordinary edit.
	Traits     *string          `json:"traits,omitempty"`
	SortOrder  *int             `json:"sort_order,omitempty"`
	Migrations []FieldMigration `json:"migrations,omitempty"`
	// ExpectedUpdatedAt, when non-empty, opts into optimistic-concurrency
	// control (BUG-2265, mirroring the item pattern from IDEA-1480): the
	// store re-reads the row's updated_at under the workspace write lock and
	// rejects the write with a conflict error when it no longer matches the
	// RFC3339 timestamp the caller last read. Empty = last-write-wins (the
	// legacy behaviour, unchanged for CLI / MCP / API callers that don't send
	// it). Never persisted; consumed by UpdateCollection only.
	ExpectedUpdatedAt string `json:"expected_updated_at,omitempty"`
}

// ErrInvalidSettingsType is returned by CollectionUpdate.UnmarshalJSON
// and CollectionCreate.UnmarshalJSON when the inbound `settings` value is
// neither a JSON object nor a JSON-encoded string. IDEA-1488: handler-
// layer shape validation ceiling, paired with the IDEA-1484 NOT NULL
// floor on collections.settings. Mirrors item.go's
// ErrInvalidFieldsType / ErrInvalidTagsType and view.go's
// ErrInvalidConfigType.
var ErrInvalidSettingsType = errors.New(`"settings" must be a JSON object or a JSON-encoded string`)

// UnmarshalJSON for CollectionCreate accepts `settings` either as the
// canonical JSON-encoded string shape (matches models.Collection.Settings
// storage) OR as the natural nested object shape any reasonable HTTP
// client would send. Mirrors ItemCreate.UnmarshalJSON; see
// flexJSONToString in item.go for the shape contract.
func (c *CollectionCreate) UnmarshalJSON(data []byte) error {
	type alias CollectionCreate
	aux := struct {
		Settings json.RawMessage `json:"settings,omitempty"`
		Traits   json.RawMessage `json:"traits,omitempty"`
		*alias
	}{alias: (*alias)(c)}

	if err := json.Unmarshal(data, &aux); err != nil {
		return err
	}

	if settingsStr, err := flexJSONToString(aux.Settings, '{', ErrInvalidSettingsType); err != nil {
		return err
	} else if settingsStr != nil {
		c.Settings = *settingsStr
	}

	// `traits` gets the same both-shapes treatment as `settings`: the field
	// is a JSON string in storage, but any reasonable client sends a nested
	// object. TASK-2657.
	if traitsStr, err := flexJSONToString(aux.Traits, '{', ErrInvalidTraitsType); err != nil {
		return err
	} else if traitsStr != nil {
		c.Traits = *traitsStr
	}

	return nil
}

// UnmarshalJSON for CollectionUpdate accepts `settings` either as the
// canonical JSON-encoded string shape OR as the natural nested object
// shape. Mirrors ItemUpdate.UnmarshalJSON; the struct field stays
// `*string` and downstream consumers are unchanged.
//
// IDEA-1488: closes the shape-validation gap that IDEA-1484's NOT NULL
// floor doesn't cover. After this lands, the writer-side store coercion
// at collections.go:248 only sees empty-string-or-valid-object input.
func (u *CollectionUpdate) UnmarshalJSON(data []byte) error {
	type alias CollectionUpdate
	aux := struct {
		Settings json.RawMessage `json:"settings,omitempty"`
		Traits   json.RawMessage `json:"traits,omitempty"`
		*alias
	}{alias: (*alias)(u)}

	if err := json.Unmarshal(data, &aux); err != nil {
		return err
	}

	settingsStr, err := flexJSONToString(aux.Settings, '{', ErrInvalidSettingsType)
	if err != nil {
		return err
	}
	u.Settings = settingsStr

	// Absent `traits` stays nil, which UpdateCollection reads as "leave the
	// declarations alone" — the case for every client that predates traits.
	// TASK-2657.
	traitsStr, err := flexJSONToString(aux.Traits, '{', ErrInvalidTraitsType)
	if err != nil {
		return err
	}
	u.Traits = traitsStr

	return nil
}