doc(sites): adding sites

Author: katallaxie

examples/.DS_Store

@@ -1,5 +1,17 @@
 version: 1
 name: example
+
+# Root directory for the builder configuration and output.
+root: .builder
+
+# Sites is a deployment target for the builder CLI.
+sites:
+  path: .
+  name: fizzy-buzzy
+  ignore:
+    - .builder
+
+# Rules define the builder's behavior and code generation rules.
 rules:
   design:
     - Document any platform-specific behavior or limitations
@@ -34,12 +46,6 @@ constitution: |
   - Tests must use path.join() for expected path values, not hardcoded strings
   - Consider case sensitivity differences in file systems
 
-deploy:
-  path: .
-  ignore:
-    - .builder
-  site: fizzy-buzzy
-
 tasks:
   feature:
     id: feature
@@ -243,4 +249,3 @@ tasks:
 
             - [ ] 2.1 <!-- Task description -->
             - [ ] 2.2 <!-- Task description -->
-root: .builder

examples/.builder.yml

@@ -114,19 +114,19 @@ func (m checkSiteModel) View() tea.View {
 	}
 
 	if m.siteExists {
-		fmt.Fprintf(&s, "%s %s exists.\n", checkMark, m.cfg.Spec.Deploy.Site)
+		fmt.Fprintf(&s, "%s %s exists.\n", checkMark, m.cfg.Spec.Sites.Site)
 	}
 
 	if !m.siteExists {
-		fmt.Fprintf(&s, "%s %s does not exist.\n", errorMark, m.cfg.Spec.Deploy.Site)
+		fmt.Fprintf(&s, "%s %s does not exist.\n", errorMark, m.cfg.Spec.Sites.Name)
 	}
 
 	return tea.NewView(s.String())
 }
 
 func (m *checkSiteModel) checkSiteExists() tea.Cmd {
 	return func() tea.Msg {
-		site := &models.Site{Name: m.cfg.Spec.Deploy.Site}
+		site := &models.Site{Name: m.cfg.Spec.Sites.Name}
 		exists, err := m.sitesCtrl.Exists(m.ctx, site)
 		if utilx.NotNil(err) {
 			return siteCheckErrorMsg{err: err}

examples/index.html

@@ -83,7 +83,7 @@ func (m *createSiteModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 // View renders the current state of the deploy model.
 func (m createSiteModel) View() tea.View {
-	s := fmt.Sprintf("%s %s successfully created.\n", checkMark, m.cfg.Spec.Deploy.Site)
+	s := fmt.Sprintf("%s %s successfully created.\n", checkMark, m.cfg.Spec.Sites.Name)
 
 	if utilx.NotNil(m.err) {
 		s = fmt.Sprintf("%s %s\n", errorMark, m.err)
@@ -94,7 +94,7 @@ func (m createSiteModel) View() tea.View {
 
 func (m *createSiteModel) createSite() tea.Cmd {
 	return func() tea.Msg {
-		site := &models.Site{Name: m.cfg.Spec.Deploy.Site}
+		site := &models.Site{Name: m.cfg.Spec.Sites.Name}
 		err := m.sitesCtrl.Create(m.ctx, site)
 		if utilx.NotNil(err) {
 			return createSiteErrorMsg{err: err}

internal/ui/models/sites/check.go

@@ -147,11 +147,11 @@ func (m deployModel) View() tea.View {
 }
 
 func (m *deployModel) writeFiles() tea.Cmd {
-	files := utils.ScanDir(m.cfg.Spec.Deploy.Path, m.cfg.Spec.Deploy.Ignore)
+	files := utils.ScanDir(m.cfg.Spec.Sites.Path, m.cfg.Spec.Sites.Ignore)
 	cmds := make([]tea.Cmd, 0, len(files))
 	m.total = len(files)
 	site := &models.Site{
-		Name: m.cfg.Spec.Deploy.Site,
+		Name: m.cfg.Spec.Sites.Name,
 	}
 
 	for _, file := range files {

internal/ui/models/sites/create.go

@@ -28,19 +28,30 @@ const (
 // This could be used in various contexts such as API specifications,
 // software design documents, etc.
 type Spec struct {
-	Version      int     `json:"version" yaml:"version"`
-	Name         string  `json:"name,omitempty" yaml:"name"`
-	Description  string  `json:"description,omitempty" yaml:"description,omitempty"`
-	Rules        Rules   `json:"rules" yaml:"rules"`
-	Constitution string  `json:"constitution" yaml:"constitution"`
-	Models       []Model `json:"models,omitempty" yaml:"models,omitempty"`
-	Deploy       *Deploy `json:"domain,omitempty" yaml:"domain,omitempty"`
-	Tasks        Tasks   `json:"tasks" yaml:"tasks"`
-	Root         string  `json:"root,omitempty" yaml:"root,omitempty"`
+	// Version is the version of the spec.
+	Version int `json:"version" yaml:"version"`
+	// Name is the name of the spec.
+	Name string `json:"name,omitempty" yaml:"name"`
+	// Root is the root directory of the spec.
+	Root string `json:"root,omitempty" yaml:"root,omitempty"`
+	// Description is the description of the spec.
+	Description string `json:"description,omitempty" yaml:"description,omitempty"`
+	// Rules define the rules for the spec.
+	Rules Rules `json:"rules" yaml:"rules"`
+	// Constitution is the constitution of the spec.
+	Constitution string `json:"constitution" yaml:"constitution"`
+	// Models define the models for the spec.
+	Models []Model `json:"models,omitempty" yaml:"models,omitempty"`
+	// Sites defines the deployment configuration for the specification.
+	Sites *Sites `json:"sites,omitempty" yaml:"sites,omitempty"`
+	// Tasks define the tasks for the spec.
+	Tasks Tasks `json:"tasks" yaml:"tasks"`
 }
 
-// Deploy defines the deployment configuration for the specification.
-type Deploy struct {
+// Sites defines the deployment configuration for the specification.
+type Sites struct {
+	// Name is the name of the site.
+	Name string `json:"name" yaml:"name"`
 	// Path is the path to the deployment configuration file.
 	Path string `json:"path" yaml:"path"`
 	// Site is the name of the site to deploy to.
@@ -51,12 +62,18 @@ type Deploy struct {
 
 // Model specifies a model.
 type Model struct {
+	// RequestOptions are the request options for the model.
 	RequestOptions map[string]any `json:"requestOptions,omitempty" yaml:"requestOptions,omitempty"`
-	ID             string         `json:"id" yaml:"id"`
-	Name           string         `json:"name" yaml:"name"`
-	URL            string         `json:"url" yaml:"url"`
-	Provider       Provider       `json:"provider" yaml:"provider"`
-	Roles          []string       `json:"roles" yaml:"roles"`
+	// ID is the unique identifier for the model.
+	ID string `json:"id" yaml:"id"`
+	// Name is the name of the model.
+	Name string `json:"name" yaml:"name"`
+	// URL is the URL of the model.
+	URL string `json:"url" yaml:"url"`
+	// Provider is the provider of the model.
+	Provider Provider `json:"provider" yaml:"provider"`
+	// Roles are the roles of the model.
+	Roles []string `json:"roles" yaml:"roles"`
 }
 
 // Provider is a string that specifies the provider for a model.
@@ -151,7 +168,7 @@ func (s *Spec) UnmarshalYAML(data []byte) error {
 		Name         string  `yaml:"name"`
 		Models       []Model `yaml:"models"`
 		Version      int     `yaml:"version"`
-		Deploy       *Deploy `yaml:"deploy"`
+		Sites        *Sites  `yaml:"deploy"`
 		Root         string  `yaml:"root"`
 	}{
 		Version: DefaultVersion,
@@ -172,7 +189,7 @@ func (s *Spec) UnmarshalYAML(data []byte) error {
 	s.Constitution = spec.Constitution
 	s.Description = spec.Description
 	s.Tasks = spec.Tasks
-	s.Deploy = spec.Deploy
+	s.Sites = spec.Sites
 	s.Root = spec.Root
 
 	return nil

internal/ui/models/sites/deploy.go

@@ -0,0 +1,25 @@
+---
+title: "Sites"
+weight: 20
+---
+
+Sites are a deployment target specifically interacting with the Builder API.
+A site is self-service, citizen-development internal hosting service.
+
+## Example
+
+```yaml {filename=".builder.yaml"}
+sites:
+  path: .
+  name: fizzy-buzzy
+  ignore:
+    - .builder
+```
+
+## Structure
+
+A site is defined by the following fields:
+
+- `path`: The path to the site's source code (default: current directory).
+- `name`: The name of the site.
+- `ignore`: A list of files to ignore when deploying the site.