Skip to content

Modern Docker Management, Designed for Everyone

feat: add ability to tag projects (#3601)

Kyle Mendell9687b138800c
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 290c1cbe5..8cd18169d 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -5,13 +5,16 @@
"workspaceFolder": "/workspace",
"features": {
"ghcr.io/devcontainers/features/go:1": {
- "version": "1.26"
- },
- "ghcr.io/devcontainers/features/node:2": {
- "version": "25",
- "pnpm": "10.22.0"
+ "version": "1.26.5"
},
- "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+ "ghcr.io/devcontainers/features/node:2": {
+ "version": "26.5.0",
+ "pnpm": "11.21.0"
+ },
+ "ghcr.io/jsburckhardt/devcontainer-features/just:1": {
+ "version": "1.58.0"
+ },
+ "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
"version": "latest",
"enableNonRootDocker": "true",
"moby": "true"
@@ -27,15 +30,14 @@
"vscode": {
"extensions": [
"golang.go",
- "dbaeumer.vscode-eslint",
- "oxc.oxc-vscode",
+ "oxc.oxc-vscode",
"svelte.svelte-vscode",
"bradlc.vscode-tailwindcss",
"ms-azuretools.vscode-docker",
"GitHub.copilot-chat",
- "GitHub.copilot",
- "ms-vscode.vscode-typescript-next",
- "actboy168.tasks"
+ "GitHub.copilot",
+ "ms-vscode.vscode-typescript-next",
+ "actboy168.tasks"
]
}
},
@@ -43,12 +45,12 @@
"source=node_modules,target=/workspace/node_modules,type=volume",
"source=pnpm_store,target=/workspace/.pnpm-store,type=volume"
],
- "postCreateCommand": "npx -y corepack enable && pnpm install && cd backend && go mod download",
+ "postCreateCommand": "just deps install all",
"remoteUser": "root",
- "containerEnv": {
- "TZ": "Pacific/Auckland",
- "GOEXPERIMENT": "jsonv2"
- },
+ "containerEnv": {
+ "TZ": "Pacific/Auckland",
+ "GOEXPERIMENT": "jsonv2"
+ },
"remoteEnv": {
"HOST_PROJECT_ROOT": "${localWorkspaceFolder}"
}
diff --git a/backend/internal/database/database_test.go b/backend/internal/database/database_test.go
index 2c7d52c29..5503173cb 100644
--- a/backend/internal/database/database_test.go
+++ b/backend/internal/database/database_test.go
@@ -202,6 +202,44 @@ func TestMigration070_PasskeysAndMFA_UpAndDown(t *testing.T) {
assert.Zero(t, columnCount)
}
+func TestMigration072_ProjectTags_UpDownAndCascade(t *testing.T) {
+ ctx := context.Background()
+ rawDB, _ := newSQLiteSQLDBInternal(t, t.TempDir(), "arcane-project-tags.db")
+ rawDB.SetMaxOpenConns(1)
+
+ require.NoError(t, migrateDatabaseToVersionInternal(ctx, rawDB, dbProviderSQLite, MigrationOptions{}, 71))
+ var tableCount int
+ require.NoError(t, rawDB.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'project_tags'`).Scan(&tableCount))
+ assert.Zero(t, tableCount)
+
+ require.NoError(t, migrateDatabaseToVersionInternal(ctx, rawDB, dbProviderSQLite, MigrationOptions{}, 72))
+ require.NoError(t, rawDB.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'project_tags'`).Scan(&tableCount))
+ assert.Equal(t, 1, tableCount)
+ var indexCount int
+ require.NoError(t, rawDB.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'index' AND name = 'idx_project_tags_name'`).Scan(&indexCount))
+ assert.Equal(t, 1, indexCount)
+
+ _, err := rawDB.Exec(`PRAGMA foreign_keys=ON`)
+ require.NoError(t, err)
+ _, err = rawDB.Exec(`INSERT INTO projects (id, name, path, status, service_count, running_count, created_at) VALUES ('project-1', 'demo', '/tmp/demo', 'stopped', 0, 0, CURRENT_TIMESTAMP)`)
+ require.NoError(t, err)
+ _, err = rawDB.Exec(`INSERT INTO project_tags (project_id, name, source) VALUES ('project-1', 'database', 'ui'), ('project-1', 'database', 'compose')`)
+ require.NoError(t, err)
+ _, err = rawDB.Exec(`INSERT INTO project_tags (project_id, name, source) VALUES ('project-1', 'database', 'ui')`)
+ require.Error(t, err)
+ _, err = rawDB.Exec(`INSERT INTO project_tags (project_id, name, source) VALUES ('project-1', 'invalid', 'other')`)
+ require.Error(t, err)
+ _, err = rawDB.Exec(`DELETE FROM projects WHERE id = 'project-1'`)
+ require.NoError(t, err)
+ var tagCount int
+ require.NoError(t, rawDB.QueryRow(`SELECT COUNT(*) FROM project_tags WHERE project_id = 'project-1'`).Scan(&tagCount))
+ assert.Zero(t, tagCount)
+
+ require.NoError(t, migrateDatabaseToVersionInternal(ctx, rawDB, dbProviderSQLite, MigrationOptions{AllowDowngrade: true}, 71))
+ require.NoError(t, rawDB.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'project_tags'`).Scan(&tableCount))
+ assert.Zero(t, tableCount)
+}
+
func TestMigration071_RenamesVolumeWorkspaceLegacyKeys(t *testing.T) {
ctx := context.Background()
rawDB, _ := newSQLiteSQLDBInternal(t, t.TempDir(), "arcane-volume-workspace-keys.db")
diff --git a/backend/internal/gitops/gitops_sync.go b/backend/internal/gitops/gitops_sync.go
index 73200b268..8409e13c7 100644
--- a/backend/internal/gitops/gitops_sync.go
+++ b/backend/internal/gitops/gitops_sync.go
@@ -1489,7 +1489,7 @@ func (s *GitOpsSyncService) createProjectForSyncInternal(ctx context.Context, sy
// Use the non-suffixing create: a GitOps sync must never mint a "-N" duplicate.
// A name collision means a project directory already exists for this name, so the
// binding is broken — fail loudly and disable auto-sync instead of duplicating.
- project, err := s.projectService.CreateProject(ctx, sync.ProjectName, composeContent, envContent, projecttypes.CreateProjectWorkspaceManifest{}, nil, actor, false)
+ project, err := s.projectService.CreateProject(ctx, sync.ProjectName, composeContent, envContent, projecttypes.CreateProjectWorkspaceManifest{}, nil, nil, nil, actor, false)
if err != nil {
if errors.Is(err, projects.ErrProjectDirExists) {
bindingErr := common.Classify(common.ErrGitOpsSyncProjectBindingBroken, errors.WrapIf(errors.Errorf("sync %s cannot create project %q: a directory with that name already exists; refusing to create a duplicate", sync.ID, projects.SanitizeProjectName(sync.ProjectName)), "GitOps sync project binding broken"))
diff --git a/backend/internal/models/project_tag.go b/backend/internal/models/project_tag.go
new file mode 100644
index 000000000..f267fa12d
--- /dev/null
+++ b/backend/internal/models/project_tag.go
@@ -0,0 +1,14 @@
+package models
+
+// ProjectTag stores one normalized tag association and its management source.
+type ProjectTag struct {
+ ProjectID string `json:"projectId" gorm:"column:project_id;primaryKey"`
+ Name string `json:"name" gorm:"column:name;primaryKey"`
+ Source string `json:"source" gorm:"column:source;primaryKey"`
+ Color string `json:"color" gorm:"column:color;not null;default:gray"`
+}
+
+// TableName returns the database table used for project tag associations.
+func (ProjectTag) TableName() string {
+ return "project_tags"
+}
diff --git a/backend/internal/project/handler.go b/backend/internal/project/handler.go
index 8a21275a7..adfbbb11a 100644
--- a/backend/internal/project/handler.go
+++ b/backend/internal/project/handler.go
@@ -29,6 +29,7 @@ import (
"github.com/getarcaneapp/arcane/types/v2/base"
"github.com/getarcaneapp/arcane/types/v2/project"
"github.com/samber/mo"
+ "gorm.io/gorm"
)
// ProjectHandler provides Huma-based project management endpoints.
@@ -50,6 +51,7 @@ type ListProjectsInput struct {
Status string `query:"status" doc:"Filter by status (comma-separated: running,stopped,partially running)"`
Updates string `query:"updates" doc:"Filter by update status (has_update, up_to_date, error, unknown)"`
Archived string `query:"archived" doc:"Archived filter: 'true' (only archived), 'all' (include archived). Default excludes archived."`
+ Tags string `query:"tags" doc:"Filter by tag names (comma-separated, OR semantics)"`
}
type ListProjectsOutput struct {
@@ -64,6 +66,28 @@ type GetProjectStatusCountsOutput struct {
Body base.ApiResponse[project.StatusCounts]
}
+// ListProjectTagsInput identifies the environment whose tag catalog is requested.
+type ListProjectTagsInput struct {
+ EnvironmentID string `path:"id" doc:"Environment ID"`
+}
+
+// ListProjectTagsOutput contains the environment's distinct project tag options.
+type ListProjectTagsOutput struct {
+ Body base.ApiResponse[[]project.TagOption]
+}
+
+// UpdateProjectTagInput identifies a project and the UI tag mutation to apply.
+type UpdateProjectTagInput struct {
+ EnvironmentID string `path:"id" doc:"Environment ID"`
+ ProjectID string `path:"projectId" doc:"Project ID"`
+ Body project.UpdateTag
+}
+
+// UpdateProjectTagOutput contains the project's effective tags after mutation.
+type UpdateProjectTagOutput struct {
+ Body base.ApiResponse[project.UpdateTagResponse]
+}
+
type DeployProjectInput struct {
EnvironmentID string `path:"id" doc:"Environment ID"`
ProjectID string `path:"projectId" doc:"Project ID"`
@@ -213,6 +237,26 @@ func RegisterProjects(api huma.API, projectService *ProjectService, activityServ
Security: handlerutil.DefaultOperationSecurity(),
}, authz.PermProjectsList, h.GetProjectStatusCounts)
+ middleware.RegisterWithPermission(api, huma.Operation{
+ OperationID: "list-project-tags",
+ Method: http.MethodGet,
+ Path: "/environments/{id}/projects/tags",
+ Summary: "List project tags",
+ Description: "Get sorted, distinct project tag names",
+ Tags: []string{"Projects"},
+ Security: handlerutil.DefaultOperationSecurity(),
+ }, authz.PermProjectsList, h.ListProjectTags)
+
+ middleware.RegisterWithPermission(api, huma.Operation{
+ OperationID: "update-project-tag",
+ Method: http.MethodPatch,
+ Path: "/environments/{id}/projects/{projectId}/tags",
+ Summary: "Update a project tag",
+ Description: "Attach or detach a UI-managed project tag",
+ Tags: []string{"Projects"},
+ Security: handlerutil.DefaultOperationSecurity(),
+ }, authz.PermProjectsUpdate, h.UpdateProjectTag)
+
middleware.RegisterWithPermission(api, huma.Operation{
OperationID: "deploy-project",
Method: http.MethodPost,
@@ -401,6 +445,9 @@ func (h *ProjectHandler) ListProjects(ctx context.Context, input *ListProjectsIn
if input.Archived != "" {
params.Filters["archived"] = input.Archived
}
+ if input.Tags != "" {
+ params.Filters["tags"] = input.Tags
+ }
projects, paginationResp, err := h.projectService.ListProjects(ctx, params)
if err != nil {
@@ -443,6 +490,63 @@ func (h *ProjectHandler) GetProjectStatusCounts(ctx context.Context, input *GetP
}, nil
}
+// ListProjectTags returns the reusable project tag catalog for an environment.
+func (h *ProjectHandler) ListProjectTags(ctx context.Context, _ *ListProjectTagsInput) (*ListProjectTagsOutput, error) {
+ options, err := h.projectService.ListProjectTagOptions(ctx)
+ if err != nil {
+ return nil, huma.Error500InternalServerError(errors.WithMessage(err, "Failed to list project tags").Error())
+ }
+ if options == nil {
+ options = []project.TagOption{}
+ }
+ return &ListProjectTagsOutput{Body: base.ApiResponse[[]project.TagOption]{Success: true, Data: options}}, nil
+}
+
+// UpdateProjectTag applies one UI-managed project tag association change.
+func (h *ProjectHandler) UpdateProjectTag(ctx context.Context, input *UpdateProjectTagInput) (*UpdateProjectTagOutput, error) {
+ user, err := handlerutil.RequireUser(ctx)
+ if err != nil {
+ return nil, err
+ }
+
+ var tags []project.Tag
+ runtimeCtx := utils.ActivityRuntimeContext(ctx, h.appCtx)
+ activityID, err := activitylib.RunHandlerActivity(runtimeCtx, h.activityService, activitylib.HandlerOptions{
+ EnvironmentID: input.EnvironmentID,
+ Type: models.ActivityTypeResourceAction,
+ ResourceType: "project",
+ ResourceID: input.ProjectID,
+ ResourceName: input.ProjectID,
+ User: user,
+ Step: "Updating project tags",
+ Message: "Updating project tags",
+ SuccessMessage: "Project tags updated",
+ Metadata: models.JSON{"action": "update_tags", "tag": input.Body.Name, "attached": input.Body.Attached},
+ }, func(runtimeCtx context.Context) error {
+ var updateErr error
+ tags, updateErr = h.projectService.UpdateProjectTag(runtimeCtx, input.ProjectID, input.Body.Name, input.Body.Color, input.Body.Attached, *user)
+ return updateErr
+ })
+ if err != nil {
+ switch {
+ case errors.Is(err, errComposeTagReadOnly):
+ return nil, huma.Error409Conflict(err.Error())
+ case errors.Is(err, gorm.ErrRecordNotFound):
+ return nil, huma.Error404NotFound("Project not found")
+ default:
+ return nil, huma.Error400BadRequest(err.Error())
+ }
+ }
+
+ return &UpdateProjectTagOutput{Body: base.ApiResponse[project.UpdateTagResponse]{
+ Success: true,
+ Data: project.UpdateTagResponse{
+ Tags: tags,
+ ActivityID: mo.EmptyableToOption(strings.TrimSpace(activityID)).ToPointer(),
+ },
+ }}, nil
+}
+
// DeployProject deploys a Docker Compose project.
// projectStreamOperationConfigInternal describes one streamed project
// operation (deploy, redeploy, pull, build): the activity it records and the
@@ -638,7 +742,7 @@ func (h *ProjectHandler) CreateProject(ctx context.Context, input *CreateProject
Metadata: models.JSON{"action": "create_project"},
}, func(runtimeCtx context.Context) error {
var createErr error
- proj, createErr = h.projectService.CreateProject(runtimeCtx, projectInput.Name, projectInput.ComposeContent, projectInput.EnvContent, manifest, uploads, *user)
+ proj, createErr = h.projectService.CreateProject(runtimeCtx, projectInput.Name, projectInput.ComposeContent, projectInput.EnvContent, manifest, uploads, projectInput.Tags, projectInput.TagColors, *user)
return createErr
})
if err != nil {
@@ -662,6 +766,10 @@ func (h *ProjectHandler) CreateProject(ctx context.Context, input *CreateProject
response.IsArchived = proj.IsArchived
response.ArchivedAt = proj.ArchivedAt
response.ActivityID = mo.EmptyableToOption(strings.TrimSpace(activityID)).ToPointer()
+ response.Tags, err = h.projectService.GetProjectTags(ctx, proj.ID)
+ if err != nil {
+ return nil, huma.Error500InternalServerError(errors.WithMessage(err, "Failed to load project tags").Error())
+ }
return &CreateProjectOutput{
Body: base.ApiResponse[project.CreateReponse]{
diff --git a/backend/internal/project/project.go b/backend/internal/project/project.go
index 5a5caf786..9bc91289b 100644
--- a/backend/internal/project/project.go
+++ b/backend/internal/project/project.go
@@ -175,6 +175,9 @@ func (s *ProjectService) CreateGitOpsManagedProject(ctx context.Context, sync *m
sync.ProjectID = &project.ID
project.GitOpsManagedBy = &sync.ID
s.composeNames.put(projects.NormalizeProjectName(project.Name), project.ID)
+ if err := s.reconcileComposeTagsForProjectInternal(ctx, project); err != nil {
+ slog.WarnContext(ctx, "failed to reconcile Compose project tags during GitOps project creation", "projectID", project.ID, "error", err)
+ }
logEvent := true
if len(logEventOptions) > 0 {
logEvent = logEventOptions[0]
diff --git a/backend/internal/project/project_details.go b/backend/internal/project/project_details.go
index 3646c61cf..8ff236535 100644
--- a/backend/internal/project/project_details.go
+++ b/backend/internal/project/project_details.go
@@ -220,6 +220,10 @@ func (s *ProjectService) GetProjectDetails(ctx context.Context, projectID string
meta := s.ProjectMetadata(ctx, *proj, nil)
applyResolvedProjectIconInternal(&resp, iconcatalog.Resolve(IconCatalogForContext(ctx), meta.ProjectIcon))
resp.URLs = meta.ProjectURLS
+ resp.Tags, err = s.GetProjectTags(ctx, projectID)
+ if err != nil {
+ return project.Details{}, err
+ }
// Default counts/status from DB (will be overridden if runtime check succeeds)
resp.ServiceCount = proj.ServiceCount
diff --git a/backend/internal/project/project_lifecycle.go b/backend/internal/project/project_lifecycle.go
index 408ab4a26..e4bc0a080 100644
--- a/backend/internal/project/project_lifecycle.go
+++ b/backend/internal/project/project_lifecycle.go
@@ -2,6 +2,7 @@ package project
import (
"context"
+ stderrors "errors"
"fmt"
"io"
"log/slog"
@@ -378,7 +379,15 @@ func (s *ProjectService) DownProject(ctx context.Context, projectID string, user
// "-N" (the interactive default). When false a collision returns
// projects.ErrProjectDirExists (wrapped) so GitOps creates fail loudly instead of
// minting runaway "-N" duplicate projects on a broken binding.
-func (s *ProjectService) CreateProject(ctx context.Context, name, composeContent string, envContent *string, manifest project.CreateProjectWorkspaceManifest, uploads map[int][]byte, user models.User, allowNameSuffixOptions ...bool) (*models.Project, error) {
+func (s *ProjectService) CreateProject(ctx context.Context, name, composeContent string, envContent *string, manifest project.CreateProjectWorkspaceManifest, uploads map[int][]byte, uiTags []string, uiTagColors map[string]project.TagColor, user models.User, allowNameSuffixOptions ...bool) (*models.Project, error) {
+ normalizedUITags, err := projects.NormalizeProjectTags(uiTags)
+ if err != nil {
+ return nil, errors.WrapIf(err, "invalid project tags")
+ }
+ normalizedTagColors, err := normalizeProjectTagColorsInternal(uiTagColors)
+ if err != nil {
+ return nil, errors.WrapIf(err, "invalid project tag colors")
+ }
allowNameSuffix := true
if len(allowNameSuffixOptions) > 0 {
allowNameSuffix = allowNameSuffixOptions[0]
@@ -443,13 +452,41 @@ func (s *ProjectService) CreateProject(ctx context.Context, name, composeContent
_ = acfs.RemoveAll(context.WithoutCancel(ctx), projectsDirectory, projectLogical)
return nil, errors.WrapIf(err, "failed to save project files")
}
+ composeMeta, err := projects.ParseArcaneComposeMetadata(
+ ctx,
+ filepath.Join(projectPath, projects.DefaultComposeFileName),
+ projectsDirectory,
+ s.settingsService.GetBoolSetting(ctx, "autoInjectEnv", false),
+ )
+ if err != nil {
+ slog.WarnContext(ctx, "failed to read Compose project tags during creation", "projectName", name, "error", err)
+ composeMeta = projects.ArcaneComposeMetadata{}
+ }
+ normalizedUITags = excludeComposeOwnedUITagsInternal(normalizedUITags, composeMeta.ProjectTags)
- if err := s.db.WithContext(ctx).Create(proj).Error; err != nil {
+ if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ if err := tx.Create(proj).Error; err != nil {
+ return err
+ }
+ return createUIProjectTagsInternal(tx, proj.ID, normalizedUITags, normalizedTagColors)
+ }); err != nil {
_ = acfs.RemoveAll(context.WithoutCancel(ctx), projectsDirectory, projectLogical)
return nil, errors.WrapIf(err, "failed to create project")
}
s.refreshComposeProjectNameInternal(ctx, proj)
s.refreshProjectImageRefsInternal(ctx, proj)
+ if err := s.reconcileComposeProjectTagsInternal(ctx, proj.ID, composeMeta.ProjectTags); err != nil {
+ cleanupCtx := context.WithoutCancel(ctx)
+ databaseCleanupErr := s.db.WithContext(cleanupCtx).Transaction(func(tx *gorm.DB) error {
+ return deleteProjectWithTagsInternal(tx, proj.ID)
+ })
+ fileCleanupErr := acfs.RemoveAll(cleanupCtx, projectsDirectory, projectLogical)
+ return nil, stderrors.Join(
+ errors.WrapIf(err, "reconcile Compose project tags"),
+ errors.WrapIf(databaseCleanupErr, "rollback project database state after tag reconciliation failure"),
+ errors.WrapIf(fileCleanupErr, "rollback project files after tag reconciliation failure"),
+ )
+ }
metadata := models.JSON{"action": "create", "projectID": proj.ID, "projectName": proj.Name, "path": projectPath}
s.logProjectEventInternal(ctx, models.EventTypeProjectCreate, proj.ID, proj.Name, user, metadata, "could not log project creation")
@@ -499,7 +536,9 @@ func (s *ProjectService) DestroyProject(ctx context.Context, projectID string, r
slog.InfoContext(ctx, "Project files removed successfully", "path", proj.Path)
}
- if err := s.db.WithContext(ctx).Delete(proj).Error; err != nil {
+ if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ return deleteProjectWithTagsInternal(tx, projectID)
+ }); err != nil {
return errors.WrapIf(err, "failed to delete project from database")
}
diff --git a/backend/internal/project/project_listing.go b/backend/internal/project/project_listing.go
index 0318c4db9..5037dc320 100644
--- a/backend/internal/project/project_listing.go
+++ b/backend/internal/project/project_listing.go
@@ -163,22 +163,21 @@ func (s *ProjectService) ListProjects(ctx context.Context, params pagination.Que
statusFilter := ""
updatesFilter := ""
archivedFilter := ""
+ tagsFilter := ""
if params.Filters != nil {
statusFilter = strings.TrimSpace(params.Filters["status"])
updatesFilter = strings.TrimSpace(params.Filters["updates"])
archivedFilter = strings.TrimSpace(params.Filters["archived"])
+ tagsFilter = strings.TrimSpace(params.Filters["tags"])
}
query = applyProjectArchivedDBFilterInternal(query, archivedFilter)
+ query = applyProjectTagsDBFilterInternal(query, tagsFilter)
if statusFilter != "" || updatesFilter != "" {
return s.listProjectsWithDerivedFiltersInternal(ctx, params, query)
}
if term := strings.TrimSpace(params.Search); term != "" {
- searchPattern := "%" + term + "%"
- query = query.Where(
- "name LIKE ? OR path LIKE ? OR status LIKE ? OR COALESCE(dir_name, '') LIKE ?",
- searchPattern, searchPattern, searchPattern, searchPattern,
- )
+ query = applyProjectSearchDBFilterInternal(query, term)
}
query = pagination.ApplyFilter(query, "status", params.Filters["status"])
@@ -194,6 +193,9 @@ func (s *ProjectService) ListProjects(ctx context.Context, params pagination.Que
// Fetch live status concurrently for all projects
result := s.fetchProjectStatusConcurrently(ctx, projectsArray)
+ if err := s.enrichProjectsWithTagsInternal(ctx, result); err != nil {
+ return nil, pagination.Response{}, err
+ }
s.enrichProjectsWithUpdateInfoInternal(ctx, projectsArray, result)
slog.DebugContext(ctx, "Completed ListProjects request",
@@ -213,6 +215,39 @@ func applyProjectArchivedDBFilterInternal(query *gorm.DB, filterValue string) *g
}
}
+func applyProjectTagsDBFilterInternal(query *gorm.DB, filterValue string) *gorm.DB {
+ names := normalizeTagFilterValuesInternal(filterValue)
+ if len(names) == 0 {
+ return query
+ }
+ return query.Where("EXISTS (SELECT 1 FROM project_tags WHERE project_tags.project_id = projects.id AND project_tags.name IN ?)", names)
+}
+
+func normalizeTagFilterValuesInternal(filterValue string) []string {
+ seen := map[string]struct{}{}
+ result := make([]string, 0)
+ for value := range strings.SplitSeq(filterValue, ",") {
+ normalized, err := projects.NormalizeProjectTag(value)
+ if err != nil {
+ continue
+ }
+ if _, exists := seen[normalized]; exists {
+ continue
+ }
+ seen[normalized] = struct{}{}
+ result = append(result, normalized)
+ }
+ return result
+}
+
+func applyProjectSearchDBFilterInternal(query *gorm.DB, term string) *gorm.DB {
+ searchPattern := "%" + strings.TrimSpace(term) + "%"
+ return query.Where(
+ "name LIKE ? OR path LIKE ? OR status LIKE ? OR COALESCE(dir_name, '') LIKE ? OR EXISTS (SELECT 1 FROM project_tags WHERE project_tags.project_id = projects.id AND LOWER(project_tags.name) LIKE ?)",
+ searchPattern, searchPattern, searchPattern, searchPattern, "%"+strings.ToLower(strings.TrimSpace(term))+"%",
+ )
+}
+
func (s *ProjectService) listProjectsWithDerivedFiltersInternal(
ctx context.Context,
params pagination.QueryParams,
@@ -245,21 +280,29 @@ func (s *ProjectService) filterProjectsWithDerivedFiltersInternal(
) (pagination.FilterResult[project.Details], error) {
var projectsArray []models.Project
if term := strings.TrimSpace(params.Search); term != "" {
- searchPattern := "%" + term + "%"
- query = query.Where(
- "name LIKE ? OR path LIKE ? OR status LIKE ? OR COALESCE(dir_name, '') LIKE ?",
- searchPattern, searchPattern, searchPattern, searchPattern,
- )
+ query = applyProjectSearchDBFilterInternal(query, term)
}
if err := query.Find(&projectsArray).Error; err != nil {
return pagination.FilterResult[project.Details]{}, errors.WrapIf(err, "failed to list projects")
}
items := s.fetchProjectStatusConcurrently(ctx, projectsArray)
+ if err := s.enrichProjectsWithTagsInternal(ctx, items); err != nil {
+ return pagination.FilterResult[project.Details]{}, err
+ }
s.enrichProjectsWithUpdateInfoInternal(ctx, projectsArray, items)
items = s.appendDiscoveredComposeProjectUpdatesInternal(ctx, params, projectsArray, items)
- return pagination.SearchOrderAndPaginate(items, params, s.buildProjectDerivedPaginationConfigInternal()), nil
+ return pagination.SearchOrderAndPaginate(items, withoutProjectDBFiltersInternal(params), s.buildProjectDerivedPaginationConfigInternal()), nil
+}
+
+func withoutProjectDBFiltersInternal(params pagination.QueryParams) pagination.QueryParams {
+ if _, exists := params.Filters["tags"]; !exists {
+ return params
+ }
+ params.Filters = maps.Clone(params.Filters)
+ delete(params.Filters, "tags")
+ return params
}
func (s *ProjectService) appendDiscoveredComposeProjectUpdatesInternal(
@@ -292,7 +335,7 @@ func shouldIncludeDiscoveredComposeProjectUpdatesInternal(params pagination.Quer
return false
}
- return strings.EqualFold(strings.TrimSpace(params.Filters["updates"]), "has_update")
+ return strings.EqualFold(strings.TrimSpace(params.Filters["updates"]), "has_update") && strings.TrimSpace(params.Filters["tags"]) == ""
}
func (s *ProjectService) buildKnownComposeProjectNameSetInternal(ctx context.Context, projectsArray []models.Project) map[string]struct{} {
@@ -531,6 +574,13 @@ func (s *ProjectService) buildProjectDerivedPaginationConfigInternal() paginatio
func(p project.Details) (string, error) { return p.RelativePath, nil },
func(p project.Details) (string, error) { return p.Status, nil },
func(p project.Details) (string, error) { return p.DirName, nil },
+ func(p project.Details) (string, error) {
+ names := make([]string, 0, len(p.Tags))
+ for _, tag := range p.Tags {
+ names = append(names, tag.Name)
+ }
+ return strings.Join(names, " "), nil
+ },
},
SortBindings: []pagination.SortBinding[project.Details]{
{
diff --git a/backend/internal/project/project_sync.go b/backend/internal/project/project_sync.go
index f036c40df..4375a398a 100644
--- a/backend/internal/project/project_sync.go
+++ b/backend/internal/project/project_sync.go
@@ -87,6 +87,9 @@ func (s *ProjectService) HandleProjectFilesChanged(ctx context.Context, paths []
for i := range affected {
s.parsedCompose.invalidate(affected[i].ID)
s.refreshProjectImageRefsInternal(ctx, &affected[i])
+ if err := s.reconcileComposeTagsForProjectInternal(ctx, &affected[i]); err != nil {
+ slog.WarnContext(ctx, "failed to reconcile Compose project tags after file change", "projectID", affected[i].ID, "error", err)
+ }
}
}
@@ -211,7 +214,7 @@ func (s *ProjectService) upsertProjectForDir(ctx context.Context, dirName, dirPa
return errors.WrapIff(cerr, "create project for %q failed", dirPath)
}
s.warnDuplicateComposeNameForPathInternal(ctx, composeMetadata.resolvedProjectName, dirPath, proj.ID)
- return nil
+ return s.reconcileComposeTagsForProjectInternal(ctx, proj)
}
if err != nil {
return errors.WrapIff(err, "query existing project for %q failed", dirPath)
@@ -242,7 +245,7 @@ func (s *ProjectService) upsertProjectForDir(ctx context.Context, dirName, dirPa
}
}
if len(updates) == 0 {
- return nil
+ return s.reconcileComposeTagsForProjectInternal(ctx, &existing)
}
updates["updated_at"] = time.Now()
@@ -255,7 +258,7 @@ func (s *ProjectService) upsertProjectForDir(ctx context.Context, dirName, dirPa
if serviceCountErr == nil {
s.warnDuplicateComposeNameForPathInternal(ctx, composeMetadata.resolvedProjectName, dirPath, existing.ID)
}
- return nil
+ return s.reconcileComposeTagsForProjectInternal(ctx, &existing)
}
func (s *ProjectService) warnDuplicateComposeNameForPathInternal(ctx context.Context, composeProjectName, dirPath, projectID string) {
@@ -445,7 +448,9 @@ func (s *ProjectService) deleteProjectDuringCleanupInternal(ctx context.Context,
logAttrs = append(logAttrs, "projectID", p.ID, "name", p.Name, "path", p.Path)
logAttrs = append(logAttrs, attrs...)
- if derr := s.db.WithContext(ctx).Delete(&models.Project{}, "id = ?", p.ID).Error; derr != nil {
+ if derr := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ return deleteProjectWithTagsInternal(tx, p.ID)
+ }); derr != nil {
slog.ErrorContext(ctx, "failed to delete project during filesystem cleanup",
append(logAttrs, "reason", reason, "error", derr)...)
return
diff --git a/backend/internal/project/project_tags.go b/backend/internal/project/project_tags.go
new file mode 100644
index 000000000..970e924bc
--- /dev/null
+++ b/backend/internal/project/project_tags.go
@@ -0,0 +1,293 @@
+package project
+
+import (
+ "context"
+ "sort"
+ "strings"
+
+ "emperror.dev/errors"
+ "github.com/getarcaneapp/arcane/backend/v2/internal/models"
+ projectpkg "github.com/getarcaneapp/arcane/backend/v2/pkg/projects"
+ projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
+ "gorm.io/gorm"
+ "gorm.io/gorm/clause"
+)
+
+var errComposeTagReadOnly = errors.New("tag is defined in Compose and can only be changed through x-arcane metadata")
+
+// GetProjectTags returns the effective UI and Compose tag associations for a project.
+func (s *ProjectService) GetProjectTags(ctx context.Context, projectID string) ([]projecttypes.Tag, error) {
+ tagsByProject, err := s.loadProjectTagsInternal(ctx, []string{projectID})
+ if err != nil {
+ return nil, err
+ }
+ return tagsByProject[projectID], nil
+}
+
+// ListProjectTagOptions returns the distinct tag names and colors available in the current environment.
+func (s *ProjectService) ListProjectTagOptions(ctx context.Context) ([]projecttypes.TagOption, error) {
+ var rows []models.ProjectTag
+ if err := s.db.WithContext(ctx).Order("name, source DESC, color").Find(&rows).Error; err != nil {
+ return nil, errors.WrapIf(err, "list project tag options")
+ }
+ options := make([]projecttypes.TagOption, 0)
+ for _, row := range rows {
+ if len(options) > 0 && options[len(options)-1].Name == row.Name {
+ continue
+ }
+ options = append(options, projecttypes.TagOption{Name: row.Name, Color: projecttypes.TagColor(row.Color)})
+ }
+ return options, nil
+}
+
+// UpdateProjectTag attaches or detaches a UI-managed tag and rejects Compose-owned names.
+func (s *ProjectService) UpdateProjectTag(ctx context.Context, projectID, name string, color projecttypes.TagColor, attached bool, user models.User) ([]projecttypes.Tag, error) {
+ normalized, err := projectpkg.NormalizeProjectTag(name)
+ if err != nil {
+ return nil, err
+ }
+ normalizedColor := projecttypes.TagColorGray
+ if attached {
+ normalizedColor, err = projectpkg.NormalizeProjectTagColor(color)
+ if err != nil {
+ return nil, err
+ }
+ }
+
+ var projectModel models.Project
+ err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&projectModel, "id = ?", projectID).Error; err != nil {
+ return errors.WrapIf(err, "find project for tag update")
+ }
+
+ var composeCount int64
+ if err := tx.Model(&models.ProjectTag{}).
+ Where("project_id = ? AND name = ? AND source = ?", projectID, normalized, projecttypes.TagSourceCompose).
+ Count(&composeCount).Error; err != nil {
+ return errors.WrapIf(err, "check Compose tag source")
+ }
+ if composeCount > 0 {
+ return errComposeTagReadOnly
+ }
+
+ if attached {
+ var existing int64
+ if err := tx.Model(&models.ProjectTag{}).
+ Where("project_id = ? AND name = ? AND source = ?", projectID, normalized, projecttypes.TagSourceUI).
+ Count(&existing).Error; err != nil {
+ return errors.WrapIf(err, "check UI tag source")
+ }
+ if existing > 0 {
+ return nil
+ }
+ var count int64
+ if err := tx.Model(&models.ProjectTag{}).
+ Where("project_id = ? AND source = ?", projectID, projecttypes.TagSourceUI).
+ Count(&count).Error; err != nil {
+ return errors.WrapIf(err, "count UI project tags")
+ }
+ if count >= projectpkg.ProjectTagsPerSourceLimit {
+ return errors.Errorf("a project cannot have more than %d UI tags", projectpkg.ProjectTagsPerSourceLimit)
+ }
+ resolvedColor, err := resolveProjectTagColorInternal(tx, normalized, normalizedColor)
+ if err != nil {
+ return err
+ }
+ row := models.ProjectTag{ProjectID: projectID, Name: normalized, Source: string(projecttypes.TagSourceUI), Color: string(resolvedColor)}
+ return errors.WrapIf(tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&row).Error, "attach UI project tag")
+ }
+
+ return errors.WrapIf(tx.Where("project_id = ? AND name = ? AND source = ?", projectID, normalized, projecttypes.TagSourceUI).
+ Delete(&models.ProjectTag{}).Error, "detach UI project tag")
+ })
+ if err != nil {
+ return nil, err
+ }
+
+ metadata := models.JSON{"action": "update_tags", "projectID": projectID, "projectName": projectModel.Name, "tag": normalized, "attached": attached}
+ s.logProjectEventInternal(ctx, models.EventTypeProjectUpdate, projectID, projectModel.Name, user, metadata, "could not log project tag update")
+ return s.GetProjectTags(ctx, projectID)
+}
+
+func (s *ProjectService) reconcileComposeProjectTagsInternal(ctx context.Context, projectID string, tags []projecttypes.TagOption) error {
+ normalized, err := normalizeComposeProjectTagsInternal(tags)
+ if err != nil {
+ return err
+ }
+ return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+ var projectModel models.Project
+ if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Select("id").First(&projectModel, "id = ?", projectID).Error; err != nil {
+ return errors.WrapIf(err, "find project for Compose tag reconciliation")
+ }
+ if err := tx.Where("project_id = ? AND source = ?", projectID, projecttypes.TagSourceCompose).Delete(&models.ProjectTag{}).Error; err != nil {
+ return errors.WrapIf(err, "clear Compose project tags")
+ }
+ if len(normalized) == 0 {
+ return nil
+ }
+ rows := make([]models.ProjectTag, 0, len(normalized))
+ for _, tag := range normalized {
+ rows = append(rows, models.ProjectTag{ProjectID: projectID, Name: tag.Name, Source: string(projecttypes.TagSourceCompose), Color: string(tag.Color)})
+ }
+ return errors.WrapIf(tx.Create(&rows).Error, "replace Compose project tags")
+ })
+}
+
+func normalizeComposeProjectTagsInternal(tags []projecttypes.TagOption) ([]projecttypes.TagOption, error) {
+ result := make([]projecttypes.TagOption, 0, min(len(tags), projectpkg.ProjectTagsPerSourceLimit))
+ seen := make(map[string]struct{}, len(tags))
+ for _, tag := range tags {
+ name, err := projectpkg.NormalizeProjectTag(tag.Name)
+ if err != nil {
+ return nil, err
+ }
+ if strings.TrimSpace(string(tag.Color)) == "" {
+ return nil, errors.New("compose tag color is required")
+ }
+ color, err := projectpkg.NormalizeProjectTagColor(tag.Color)
+ if err != nil {
+ return nil, err
+ }
+ if _, exists := seen[name]; exists {
+ continue
+ }
+ if len(result) >= projectpkg.ProjectTagsPerSourceLimit {
+ return nil, errors.Errorf("a project cannot have more than %d compose tags", projectpkg.ProjectTagsPerSourceLimit)
+ }
+ seen[name] = struct{}{}
+ result = append(result, projecttypes.TagOption{Name: name, Color: color})
+ }
+ return result, nil
+}
+
+func createUIProjectTagsInternal(tx *gorm.DB, projectID string, tags []string, colors map[string]projecttypes.TagColor) error {
+ if len(tags) == 0 {
+ return nil
+ }
+ rows := make([]models.ProjectTag, 0, len(tags))
+ for _, tag := range tags {
+ color, err := resolveProjectTagColorInternal(tx, tag, colors[tag])
+ if err != nil {
+ return err
+ }
+ rows = append(rows, models.ProjectTag{ProjectID: projectID, Name: tag, Source: string(projecttypes.TagSourceUI), Color: string(color)})
+ }
+ return errors.WrapIf(tx.Create(&rows).Error, "attach initial project tags")
+}
+
+func resolveProjectTagColorInternal(tx *gorm.DB, name string, fallback projecttypes.TagColor) (projecttypes.TagColor, error) {
+ var row models.ProjectTag
+ err := tx.Where("name = ?", name).Order("source DESC, color").First(&row).Error
+ switch {
+ case err == nil:
+ return projecttypes.TagColor(row.Color), nil
+ case errors.Is(err, gorm.ErrRecordNotFound):
+ return projectpkg.NormalizeProjectTagColor(fallback)
+ default:
+ return "", errors.WrapIf(err, "resolve project tag color")
+ }
+}
+
+func normalizeProjectTagColorsInternal(colors map[string]projecttypes.TagColor) (map[string]projecttypes.TagColor, error) {
+ result := make(map[string]projecttypes.TagColor, len(colors))
+ for name, color := range colors {
+ normalizedName, err := projectpkg.NormalizeProjectTag(name)
+ if err != nil {
+ return nil, err
+ }
+ normalizedColor, err := projectpkg.NormalizeProjectTagColor(color)
+ if err != nil {
+ return nil, err
+ }
+ result[normalizedName] = normalizedColor
+ }
+ return result, nil
+}
+
+func excludeComposeOwnedUITagsInternal(uiTags []string, composeTags []projecttypes.TagOption) []string {
+ composeOwned := make(map[string]struct{}, len(composeTags))
+ for _, tag := range composeTags {
+ composeOwned[tag.Name] = struct{}{}
+ }
+ result := make([]string, 0, len(uiTags))
+ for _, tag := range uiTags {
+ if _, exists := composeOwned[tag]; !exists {
+ result = append(result, tag)
+ }
+ }
+ return result
+}
+
+func deleteProjectWithTagsInternal(tx *gorm.DB, projectID string) error {
+ if err := tx.Where("project_id = ?", projectID).Delete(&models.ProjectTag{}).Error; err != nil {
+ return errors.WrapIf(err, "delete project tags")
+ }
+ return errors.WrapIf(tx.Delete(&models.Project{}, "id = ?", projectID).Error, "delete project")
+}
+
+func (s *ProjectService) reconcileComposeTagsForProjectInternal(ctx context.Context, projectModel *models.Project) error {
+ if projectModel == nil {
+ return nil
+ }
+ composeFile, err := s.ResolveProjectComposeFile(ctx, projectModel)
+ if err != nil {
+ return errors.WrapIf(err, "resolve Compose file for tag reconciliation")
+ }
+ projectsDirectory, err := s.GetProjectsDirectory(ctx)
+ if err != nil {
+ return err
+ }
+ meta, err := projectpkg.ParseArcaneComposeMetadata(ctx, composeFile, projectsDirectory, s.settingsService.GetBoolSetting(ctx, "autoInjectEnv", false))
+ if err != nil {
+ return err
+ }
+ if !meta.ProjectTagsAuthoritative {
+ return nil
+ }
+ return s.reconcileComposeProjectTagsInternal(ctx, projectModel.ID, meta.ProjectTags)
+}
+
+func (s *ProjectService) loadProjectTagsInternal(ctx context.Context, projectIDs []string) (map[string][]projecttypes.Tag, error) {
+ result := make(map[string][]projecttypes.Tag, len(projectIDs))
+ if len(projectIDs) == 0 {
+ return result, nil
+ }
+ var rows []models.ProjectTag
+ if err := s.db.WithContext(ctx).Where("project_id IN ?", projectIDs).Order("project_id, name, source, color").Find(&rows).Error; err != nil {
+ return nil, errors.WrapIf(err, "load project tags")
+ }
+ for _, row := range rows {
+ tags := result[row.ProjectID]
+ if len(tags) == 0 || tags[len(tags)-1].Name != row.Name {
+ tags = append(tags, projecttypes.Tag{Name: row.Name, Color: projecttypes.TagColor(row.Color)})
+ }
+ tags[len(tags)-1].Sources = append(tags[len(tags)-1].Sources, projecttypes.TagSource(row.Source))
+ result[row.ProjectID] = tags
+ }
+ for projectID := range result {
+ sort.SliceStable(result[projectID], func(i, j int) bool { return result[projectID][i].Name < result[projectID][j].Name })
+ for index := range result[projectID] {
+ sort.SliceStable(result[projectID][index].Sources, func(i, j int) bool {
+ return result[projectID][index].Sources[i] == projecttypes.TagSourceUI && result[projectID][index].Sources[j] != projecttypes.TagSourceUI
+ })
+ }
+ }
+ return result, nil
+}
+
+func (s *ProjectService) enrichProjectsWithTagsInternal(ctx context.Context, items []projecttypes.Details) error {
+ projectIDs := make([]string, 0, len(items))
+ for _, item := range items {
+ if item.ID != "" && !item.IsDiscovered && !strings.HasPrefix(item.ID, "compose:") {
+ projectIDs = append(projectIDs, item.ID)
+ }
+ }
+ tagsByProject, err := s.loadProjectTagsInternal(ctx, projectIDs)
+ if err != nil {
+ return err
+ }
+ for index := range items {
+ items[index].Tags = tagsByProject[items[index].ID]
+ }
+ return nil
+}
diff --git a/backend/internal/project/project_tags_test.go b/backend/internal/project/project_tags_test.go
new file mode 100644
index 000000000..897bcb219
--- /dev/null
+++ b/backend/internal/project/project_tags_test.go
@@ -0,0 +1,79 @@
+package project
+
+import (
+ "context"
+ "testing"
+
+ "github.com/getarcaneapp/arcane/backend/v2/internal/models"
+ projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
+ "github.com/stretchr/testify/require"
+)
+
+func TestProjectTags_ReconcilePreservesUIAndComposeOwnershipIsReadOnly(t *testing.T) {
+ db := setupProjectTestDB(t)
+ service := &ProjectService{db: db}
+ ctx := context.Background()
+ projectModel := models.Project{
+ BaseModel: models.BaseModel{ID: "project-tags"},
+ Name: "tagged",
+ Path: "/tmp/tagged",
+ Status: models.ProjectStatusStopped,
+ IsArchived: true,
+ GitOpsManagedBy: new("gitops-1"),
+ }
+ require.NoError(t, db.Create(&projectModel).Error)
+
+ tags, err := service.UpdateProjectTag(ctx, projectModel.ID, " Database ", projecttypes.TagColorPurple, true, models.User{})
+ require.NoError(t, err)
+ require.Equal(t, []projecttypes.Tag{{Name: "database", Color: projecttypes.TagColorPurple, Sources: []projecttypes.TagSource{projecttypes.TagSourceUI}}}, tags)
+
+ require.NoError(t, service.reconcileComposeProjectTagsInternal(ctx, projectModel.ID, []projecttypes.TagOption{
+ {Name: "DATABASE", Color: projecttypes.TagColorBlue},
+ {Name: "maintenance-window", Color: projecttypes.TagColorOrange},
+ }))
+ tags, err = service.GetProjectTags(ctx, projectModel.ID)
+ require.NoError(t, err)
+ require.Equal(t, []projecttypes.Tag{
+ {Name: "database", Color: projecttypes.TagColorBlue, Sources: []projecttypes.TagSource{projecttypes.TagSourceUI, projecttypes.TagSourceCompose}},
+ {Name: "maintenance-window", Color: projecttypes.TagColorOrange, Sources: []projecttypes.TagSource{projecttypes.TagSourceCompose}},
+ }, tags)
+
+ _, err = service.UpdateProjectTag(ctx, projectModel.ID, "database", "", false, models.User{})
+ require.ErrorIs(t, err, errComposeTagReadOnly)
+ _, err = service.UpdateProjectTag(ctx, projectModel.ID, "maintenance-window", projecttypes.TagColorBlue, true, models.User{})
+ require.ErrorIs(t, err, errComposeTagReadOnly)
+
+ require.NoError(t, service.reconcileComposeProjectTagsInternal(ctx, projectModel.ID, nil))
+ tags, err = service.UpdateProjectTag(ctx, projectModel.ID, "database", "", false, models.User{})
+ require.NoError(t, err)
+ require.Empty(t, tags)
+}
+
+func TestProjectTags_FilterUsesExactORNames(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+ projects := []models.Project{
+ {BaseModel: models.BaseModel{ID: "one"}, Name: "one", Path: "/tmp/one", Status: models.ProjectStatusStopped},
+ {BaseModel: models.BaseModel{ID: "two"}, Name: "two", Path: "/tmp/two", Status: models.ProjectStatusStopped},
+ {BaseModel: models.BaseModel{ID: "three"}, Name: "three", Path: "/tmp/three", Status: models.ProjectStatusStopped},
+ }
+ require.NoError(t, db.Create(&projects).Error)
+ require.NoError(t, db.Create(&[]models.ProjectTag{
+ {ProjectID: "one", Name: "database", Source: string(projecttypes.TagSourceUI)},
+ {ProjectID: "two", Name: "maintenance", Source: string(projecttypes.TagSourceCompose)},
+ {ProjectID: "three", Name: "database-prod", Source: string(projecttypes.TagSourceUI)},
+ }).Error)
+
+ var result []models.Project
+ err := applyProjectTagsDBFilterInternal(db.WithContext(ctx).Model(&models.Project{}), " DATABASE,maintenance ").Order("id").Find(&result).Error
+ require.NoError(t, err)
+ require.Len(t, result, 2)
+ require.ElementsMatch(t, []string{"one", "two"}, []string{result[0].ID, result[1].ID})
+ require.NotContains(t, []string{result[0].ID, result[1].ID}, "three")
+
+ result = nil
+ err = applyProjectSearchDBFilterInternal(db.WithContext(ctx).Model(&models.Project{}), "MAINT").Find(&result).Error
+ require.NoError(t, err)
+ require.Len(t, result, 1)
+ require.Equal(t, "two", result[0].ID)
+}
diff --git a/backend/internal/project/project_update.go b/backend/internal/project/project_update.go
index dbdb3bcc2..c0d2967be 100644
--- a/backend/internal/project/project_update.go
+++ b/backend/internal/project/project_update.go
@@ -229,6 +229,9 @@ func (s *ProjectService) refreshProjectAfterContentUpdateInternal(ctx context.Co
s.refreshComposeProjectNameInternal(ctx, proj)
s.refreshProjectImageRefsInternal(ctx, proj)
+ if err := s.reconcileComposeTagsForProjectInternal(ctx, proj); err != nil {
+ slog.WarnContext(ctx, "failed to reconcile Compose project tags after project update", "projectID", proj.ID, "error", err)
+ }
if err := s.updateProjectStatusandCountsInternal(ctx, proj.ID, proj.Status); err != nil {
slog.WarnContext(ctx, "failed to update service counts after compose edit", "projectID", proj.ID, "error", err)
}
@@ -266,6 +269,9 @@ func (s *ProjectService) ApplyGitSyncProjectFiles(ctx context.Context, projectID
}
s.refreshComposeProjectNameInternal(ctx, &proj)
s.refreshProjectImageRefsInternal(ctx, &proj)
+ if err := s.reconcileComposeTagsForProjectInternal(ctx, &proj); err != nil {
+ slog.WarnContext(ctx, "failed to reconcile Compose project tags after git sync", "projectID", proj.ID, "error", err)
+ }
// Recalculate service counts and status after compose file sync
if err := s.updateProjectStatusandCountsInternal(ctx, proj.ID, proj.Status); err != nil {
diff --git a/backend/internal/project/service_test.go b/backend/internal/project/service_test.go
index ee9919508..310a59fda 100644
--- a/backend/internal/project/service_test.go
+++ b/backend/internal/project/service_test.go
@@ -77,7 +77,7 @@ func setupProjectTestDB(t *testing.T) *database.DB {
t.Helper()
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
require.NoError(t, err)
- require.NoError(t, db.AutoMigrate(&models.Project{}, &models.SettingVariable{}, &models.ImageUpdateRecord{}, &models.Event{}))
+ require.NoError(t, db.AutoMigrate(&models.Project{}, &models.ProjectTag{}, &models.SettingVariable{}, &models.ImageUpdateRecord{}, &models.Event{}))
return &database.DB{DB: db}
}
@@ -2108,7 +2108,7 @@ services:
image: nginx:alpine
`
- project, err := svc.CreateProject(ctx, "with-external-include", compose, nil, projecttypes.CreateProjectWorkspaceManifest{}, nil, models.User{
+ project, err := svc.CreateProject(ctx, "with-external-include", compose, nil, projecttypes.CreateProjectWorkspaceManifest{}, nil, nil, nil, models.User{
BaseModel: models.BaseModel{ID: "u1"},
Username: "tester",
})
@@ -2185,6 +2185,8 @@ func TestProjectService_CreateProject_CommitsWorkspaceAndConfigurationTogether(t
new("VALUE=one\n"),
manifest,
map[int][]byte{0: []byte("workspace content\n")},
+ nil,
+ nil,
models.User{BaseModel: models.BaseModel{ID: "u1"}, Username: "tester"},
)
require.NoError(t, err)
@@ -2217,6 +2219,8 @@ func TestProjectService_CreateProject_RollsBackInvalidWorkspaceManifest(t *testi
nil,
manifest,
nil,
+ nil,
+ nil,
models.User{BaseModel: models.BaseModel{ID: "u1"}, Username: "tester"},
)
require.Error(t, err)
diff --git a/backend/pkg/projects/custom_labels.go b/backend/pkg/projects/custom_labels.go
index ac10976cd..51727e78e 100644
--- a/backend/pkg/projects/custom_labels.go
+++ b/backend/pkg/projects/custom_labels.go
@@ -3,6 +3,7 @@ package projects
import (
"context"
+ "log/slog"
"maps"
"os"
"path/filepath"
@@ -13,6 +14,7 @@ import (
composetypes "github.com/compose-spec/compose-go/v2/types"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/iconcatalog"
+ projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
"go.yaml.in/yaml/v4"
)
@@ -30,6 +32,7 @@ const (
arcaneIconLightKey = "icon-light"
arcaneIconDarkKey = "icon-dark"
arcaneURLsKey = "urls"
+ arcaneTagsKey = "tags"
)
type IconSet = iconcatalog.IconSet
@@ -40,6 +43,10 @@ type ArcaneComposeMetadata struct {
ProjectIcon IconSet
// ProjectURLS are additional URLs related to the project (e.g., documentation, homepage).
ProjectURLS []string
+ // ProjectTags are normalized tags managed by Compose metadata.
+ ProjectTags []projecttypes.TagOption
+ // ProjectTagsAuthoritative reports whether every Compose tag was parsed successfully.
+ ProjectTagsAuthoritative bool
// ServiceIconSets maps service names to their fallback, light, and dark icon values.
ServiceIconSets map[string]IconSet
}
@@ -107,7 +114,7 @@ func parseArcaneComposeMetadataFromFileInternal(ctx context.Context, composeFile
}
includedMeta, err := parseArcaneComposeMetadataFromFileInternal(ctx, resolvedPath, mergedEnv, visited)
if err != nil {
- continue
+ return meta, errors.WrapIff(err, "load included Compose metadata %s", resolvedPath)
}
mergeArcaneComposeMetadata(&meta, includedMeta)
}
@@ -122,7 +129,7 @@ func extractArcaneComposeMetadata(project *composetypes.Project) ArcaneComposeMe
}
if arcaneBlock, ok := project.Extensions[arcaneBlockKey]; ok {
- meta.ProjectIcon, meta.ProjectURLS = parseArcaneBlockInternal(arcaneBlock)
+ meta.ProjectIcon, meta.ProjectURLS, meta.ProjectTags, meta.ProjectTagsAuthoritative = parseArcaneBlockInternal(arcaneBlock)
}
for name, svc := range project.Services {
@@ -132,7 +139,7 @@ func extractArcaneComposeMetadata(project *composetypes.Project) ArcaneComposeMe
}
if iconSet.IsEmpty() {
if arcaneBlock, ok := svc.Extensions[arcaneBlockKey]; ok {
- iconSet, _ = parseArcaneBlockInternal(arcaneBlock)
+ iconSet, _, _, _ = parseArcaneBlockInternal(arcaneBlock)
}
}
if !iconSet.IsEmpty() {
@@ -143,10 +150,10 @@ func extractArcaneComposeMetadata(project *composetypes.Project) ArcaneComposeMe
return meta
}
-func parseArcaneBlockInternal(block any) (IconSet, []string) {
+func parseArcaneBlockInternal(block any) (IconSet, []string, []projecttypes.TagOption, bool) {
arcaneBlock, ok := utils.AsStringMap(block).Get()
if !ok {
- return IconSet{}, nil
+ return IconSet{}, nil, nil, false
}
icon := IconSet{
Icon: utils.FirstNonEmpty(
@@ -157,7 +164,78 @@ func parseArcaneBlockInternal(block any) (IconSet, []string) {
Dark: utils.FirstNonEmpty(utils.Collect(arcaneBlock[arcaneIconDarkKey], utils.ToString)...),
}
urls := utils.UniqueNonEmptyStrings(utils.Collect(arcaneBlock[arcaneURLsKey], utils.ToString))
- return icon, urls
+ tags, tagsAuthoritative := parseComposeTagsInternal(arcaneBlock[arcaneTagsKey])
+ return icon, urls, tags, tagsAuthoritative
+}
+
+func parseComposeTagsInternal(value any) ([]projecttypes.TagOption, bool) {
+ values, ok := value.([]any)
+ if !ok {
+ if value != nil {
+ slog.Warn("skipping invalid x-arcane tags; expected a list of name/color objects")
+ return nil, false
+ }
+ return nil, true
+ }
+
+ tags := make([]projecttypes.TagOption, 0, min(len(values), ProjectTagsPerSourceLimit))
+ seen := make(map[string]struct{}, len(values))
+ authoritative := true
+ for index, value := range values {
+ definition, ok := utils.AsStringMap(value).Get()
+ if !ok {
+ slog.Warn("skipping invalid x-arcane tag; expected a name/color object", "index", index)
+ authoritative = false
+ continue
+ }
+ nameValue := utils.ToString(definition["name"])
+ colorValue := utils.ToString(definition["color"])
+ if nameValue == "" || colorValue == "" {
+ slog.Warn("skipping invalid x-arcane tag; name and color are required", "index", index)
+ authoritative = false
+ continue
+ }
+ name, err := NormalizeProjectTag(nameValue)
+ if err != nil {
+ slog.Warn("skipping invalid x-arcane tag", "index", index, "error", err)
+ authoritative = false
+ continue
+ }
+ color, err := NormalizeProjectTagColor(projecttypes.TagColor(colorValue))
+ if err != nil {
+ slog.Warn("skipping invalid x-arcane tag color", "index", index, "tag", name, "error", err)
+ authoritative = false
+ continue
+ }
+ if _, exists := seen[name]; exists {
+ continue
+ }
+ if len(tags) >= ProjectTagsPerSourceLimit {
+ slog.Warn("skipping x-arcane tags over per-project limit", "limit", ProjectTagsPerSourceLimit)
+ authoritative = false
+ break
+ }
+ seen[name] = struct{}{}
+ tags = append(tags, projecttypes.TagOption{Name: name, Color: color})
+ }
+ return tags, authoritative
+}
+
+func mergeComposeTagsInternal(target, source []projecttypes.TagOption) []projecttypes.TagOption {
+ merged := make([]projecttypes.TagOption, 0, min(len(target)+len(source), ProjectTagsPerSourceLimit))
+ seen := make(map[string]struct{}, len(target)+len(source))
+ for _, tag := range append(target, source...) {
+ if _, exists := seen[tag.Name]; exists {
+ continue
+ }
+ if len(merged) >= ProjectTagsPerSourceLimit {
+ slog.Warn("skipping included x-arcane tags over per-project limit", "limit", ProjectTagsPerSourceLimit)
+ break
+ }
+ seen[tag.Name] = struct{}{}
+ merged = append(merged, tag)
+ }
+ return merged
}
func mergeArcaneComposeMetadata(target *ArcaneComposeMetadata, source ArcaneComposeMetadata) {
@@ -168,6 +246,8 @@ func mergeArcaneComposeMetadata(target *ArcaneComposeMetadata, source ArcaneComp
target.ProjectIcon = mergeIconSetFieldsInternal(target.ProjectIcon, source.ProjectIcon)
target.ProjectURLS = utils.UniqueNonEmptyStrings(append(target.ProjectURLS, source.ProjectURLS...))
+ target.ProjectTags = mergeComposeTagsInternal(target.ProjectTags, source.ProjectTags)
+ target.ProjectTagsAuthoritative = target.ProjectTagsAuthoritative && source.ProjectTagsAuthoritative
if target.ServiceIconSets == nil {
target.ServiceIconSets = map[string]IconSet{}
@@ -192,7 +272,8 @@ func mergeIconSetFieldsInternal(target, source IconSet) IconSet {
func emptyArcaneComposeMetadataInternal() ArcaneComposeMetadata {
return ArcaneComposeMetadata{
- ServiceIconSets: map[string]IconSet{},
+ ProjectTagsAuthoritative: true,
+ ServiceIconSets: map[string]IconSet{},
}
}
diff --git a/backend/pkg/projects/custom_labels_test.go b/backend/pkg/projects/custom_labels_test.go
index a282f0507..a004a862d 100644
--- a/backend/pkg/projects/custom_labels_test.go
+++ b/backend/pkg/projects/custom_labels_test.go
@@ -6,6 +6,7 @@ import (
"path/filepath"
"testing"
+ projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
"github.com/stretchr/testify/require"
)
@@ -87,6 +88,39 @@ services:
require.Equal(t, []string{"https://example.com/docs"}, meta.ProjectURLS)
}
+func TestParseArcaneComposeMetadata_TagNamesColorsInterpolationAndIncludes(t *testing.T) {
+ tempDir := t.TempDir()
+ require.NoError(t, os.WriteFile(filepath.Join(tempDir, ".env"), []byte("PROJECT_KIND=Database\nPROJECT_COLOR=Purple\n"), 0o600))
+ require.NoError(t, os.WriteFile(filepath.Join(tempDir, "compose.yaml"), []byte(`include:
+ - included.yaml
+x-arcane:
+ tags:
+ - name: ${PROJECT_KIND}
+ color: ${PROJECT_COLOR}
+services:
+ app:
+ image: nginx:alpine
+`), 0o600))
+ require.NoError(t, os.WriteFile(filepath.Join(tempDir, "included.yaml"), []byte(`x-arcane:
+ tags:
+ - name: maintenance-window
+ color: orange
+ - name: DATABASE
+ color: red
+ - name: invalid-color
+ color: chartreuse
+ - name: missing-color
+services: {}
+`), 0o600))
+
+ meta, err := ParseArcaneComposeMetadata(context.Background(), filepath.Join(tempDir, "compose.yaml"), tempDir, false)
+ require.NoError(t, err)
+ require.Equal(t, []projecttypes.TagOption{
+ {Name: "database", Color: projecttypes.TagColorPurple},
+ {Name: "maintenance-window", Color: projecttypes.TagColorOrange},
+ }, meta.ProjectTags)
+}
+
func TestParseArcaneComposeMetadata_LoadsGlobalEnvForIncludedMetadata(t *testing.T) {
projectsRoot := t.TempDir()
projectDir := filepath.Join(projectsRoot, "demo")
diff --git a/backend/pkg/projects/project_tags.go b/backend/pkg/projects/project_tags.go
new file mode 100644
index 000000000..b4c6f8044
--- /dev/null
+++ b/backend/pkg/projects/project_tags.go
@@ -0,0 +1,81 @@
+package projects
+
+import (
+ "errors"
+ "fmt"
+ "strings"
+ "unicode"
+
+ projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
+)
+
+const (
+ // ProjectTagMaxLength is the maximum number of Unicode characters in a tag name.
+ ProjectTagMaxLength = 64
+ // ProjectTagsPerSourceLimit is the maximum number of UI or Compose tags on one project.
+ ProjectTagsPerSourceLimit = 50
+)
+
+var projectTagColorsInternal = map[projecttypes.TagColor]struct{}{
+ projecttypes.TagColorGray: {},
+ projecttypes.TagColorPurple: {},
+ projecttypes.TagColorBlue: {},
+ projecttypes.TagColorGreen: {},
+ projecttypes.TagColorYellow: {},
+ projecttypes.TagColorOrange: {},
+ projecttypes.TagColorRed: {},
+ projecttypes.TagColorPink: {},
+}
+
+// NormalizeProjectTag validates and normalizes a project tag name.
+func NormalizeProjectTag(name string) (string, error) {
+ normalized := strings.ToLower(strings.TrimSpace(name))
+ if normalized == "" {
+ return "", errors.New("tag name cannot be empty")
+ }
+ if len([]rune(normalized)) > ProjectTagMaxLength {
+ return "", fmt.Errorf("tag name cannot exceed %d characters", ProjectTagMaxLength)
+ }
+ if strings.ContainsRune(normalized, ',') {
+ return "", errors.New("tag name cannot contain commas")
+ }
+ for _, char := range normalized {
+ if unicode.IsControl(char) {
+ return "", errors.New("tag name cannot contain control characters")
+ }
+ }
+ return normalized, nil
+}
+
+// NormalizeProjectTags validates, normalizes, and de-duplicates project tags.
+func NormalizeProjectTags(names []string) ([]string, error) {
+ result := make([]string, 0, min(len(names), ProjectTagsPerSourceLimit))
+ seen := make(map[string]struct{}, len(names))
+ for _, name := range names {
+ normalized, err := NormalizeProjectTag(name)
+ if err != nil {
+ return nil, err
+ }
+ if _, exists := seen[normalized]; exists {
+ continue
+ }
+ if len(result) >= ProjectTagsPerSourceLimit {
+ return nil, fmt.Errorf("a project cannot have more than %d tags per source", ProjectTagsPerSourceLimit)
+ }
+ seen[normalized] = struct{}{}
+ result = append(result, normalized)
+ }
+ return result, nil
+}
+
+// NormalizeProjectTagColor validates and normalizes a project tag color.
+func NormalizeProjectTagColor(color projecttypes.TagColor) (projecttypes.TagColor, error) {
+ normalized := projecttypes.TagColor(strings.ToLower(strings.TrimSpace(string(color))))
+ if normalized == "" {
+ return projecttypes.TagColorGray, nil
+ }
+ if _, valid := projectTagColorsInternal[normalized]; !valid {
+ return "", fmt.Errorf("unsupported tag color %q", color)
+ }
+ return normalized, nil
+}
diff --git a/backend/pkg/projects/project_tags_test.go b/backend/pkg/projects/project_tags_test.go
new file mode 100644
index 000000000..c0e6eb347
--- /dev/null
+++ b/backend/pkg/projects/project_tags_test.go
@@ -0,0 +1,26 @@
+package projects
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestNormalizeProjectTags(t *testing.T) {
+ tags, err := NormalizeProjectTags([]string{" Database ", "DATABASE", "maintenance-window"})
+ require.NoError(t, err)
+ require.Equal(t, []string{"database", "maintenance-window"}, tags)
+
+ for _, invalid := range []string{"", "bad,tag", "bad\ntag", strings.Repeat("a", ProjectTagMaxLength+1)} {
+ _, err := NormalizeProjectTag(invalid)
+ require.Error(t, err, invalid)
+ }
+
+ tooMany := make([]string, ProjectTagsPerSourceLimit+1)
+ for index := range tooMany {
+ tooMany[index] = "tag-" + strings.Repeat("x", index/10) + string(rune('a'+index%10))
+ }
+ _, err = NormalizeProjectTags(tooMany)
+ require.Error(t, err)
+}
diff --git a/backend/resources/migrations/postgres/072_add_project_tags.sql b/backend/resources/migrations/postgres/072_add_project_tags.sql
new file mode 100644
index 000000000..4037a5cba
--- /dev/null
+++ b/backend/resources/migrations/postgres/072_add_project_tags.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+CREATE TABLE project_tags (
+ project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+ name TEXT NOT NULL,
+ source TEXT NOT NULL CHECK (source IN ('ui', 'compose')),
+ color TEXT NOT NULL DEFAULT 'gray' CHECK (color IN ('gray', 'purple', 'blue', 'green', 'yellow', 'orange', 'red', 'pink')),
+ PRIMARY KEY (project_id, name, source)
+);
+
+CREATE INDEX idx_project_tags_name ON project_tags(name);
+
+-- +goose Down
+DROP TABLE IF EXISTS project_tags;
diff --git a/backend/resources/migrations/sqlite/072_add_project_tags.sql b/backend/resources/migrations/sqlite/072_add_project_tags.sql
new file mode 100644
index 000000000..9df8e7d28
--- /dev/null
+++ b/backend/resources/migrations/sqlite/072_add_project_tags.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+CREATE TABLE project_tags (
+ project_id TEXT NOT NULL,
+ name TEXT NOT NULL,
+ source TEXT NOT NULL CHECK (source IN ('ui', 'compose')),
+ color TEXT NOT NULL DEFAULT 'gray' CHECK (color IN ('gray', 'purple', 'blue', 'green', 'yellow', 'orange', 'red', 'pink')),
+ PRIMARY KEY (project_id, name, source),
+ FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_project_tags_name ON project_tags(name);
+
+-- +goose Down
+DROP TABLE IF EXISTS project_tags;
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index 7d328ebe7..14f91f14e 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -62,6 +62,19 @@
"common_configuration": "Configuration",
"common_limit": "Limit",
"common_tags": "Tags",
+ "project_tags_add": "Add tag",
+ "project_tags_create": "Create tag \"{name}\"",
+ "project_tags_create_prompt": "Create new tag",
+ "project_tags_color_gray": "Gray",
+ "project_tags_color_purple": "Purple",
+ "project_tags_color_blue": "Blue",
+ "project_tags_color_green": "Green",
+ "project_tags_color_yellow": "Yellow",
+ "project_tags_color_orange": "Orange",
+ "project_tags_color_red": "Red",
+ "project_tags_color_pink": "Pink",
+ "project_tags_search": "Search or create a tag…",
+ "project_tags_defined_in_compose": "Defined in Compose",
"common_subnet": "Subnet",
"common_shell": "Shell",
"common_ports": "Ports",
diff --git a/frontend/src/lib/components/arcane-table/arcane-table-toolbar.svelte b/frontend/src/lib/components/arcane-table/arcane-table-toolbar.svelte
index f8ef7a4a5..33c44501d 100644
--- a/frontend/src/lib/components/arcane-table/arcane-table-toolbar.svelte
+++ b/frontend/src/lib/components/arcane-table/arcane-table-toolbar.svelte
@@ -74,6 +74,8 @@
);
const typeColumn = $derived(table.getAllColumns().some((col) => col.id === 'type') ? table.getColumn('type') : undefined);
const typeColumnFilterOptions = $derived(typeColumn?.columnDef.meta?.filterOptions ?? []);
+ const tagsColumn = $derived(table.getAllColumns().some((col) => col.id === 'tags') ? table.getColumn('tags') : undefined);
+ const tagsColumnFilterOptions = $derived(tagsColumn?.columnDef.meta?.filterOptions ?? []);
const debouncedSetGlobal = debounced((v: string) => table.setGlobalFilter(v), 300);
const imageNameFilterOptionsFormatted = $derived(imageNameFilterOptions.map((name) => ({ label: name, value: name })));
@@ -84,6 +86,7 @@
const hasFilterColumns = $derived(
!withoutFilters &&
(!!(typeColumn && typeColumnFilterOptions.length > 0) ||
+ !!(tagsColumn && tagsColumnFilterOptions.length > 0) ||
!!usageColumn ||
!!updatesColumn ||
!!severityColumn ||
@@ -98,6 +101,9 @@
{#if typeColumn && typeColumnFilterOptions.length > 0}
<DataTableFacetedFilter column={typeColumn} title={m.common_type()} options={typeColumnFilterOptions} />
{/if}
+ {#if tagsColumn && tagsColumnFilterOptions.length > 0}
+ <DataTableFacetedFilter column={tagsColumn} title={m.common_tags()} options={tagsColumnFilterOptions} />
+ {/if}
{#if usageColumn}
<DataTableFacetedFilter column={usageColumn} title={m.common_usage()} options={usageFilters} />
{/if}
diff --git a/frontend/src/lib/components/arcane-table/arcane-table.svelte b/frontend/src/lib/components/arcane-table/arcane-table.svelte
index 6093c0ab4..c4182621f 100644
--- a/frontend/src/lib/components/arcane-table/arcane-table.svelte
+++ b/frontend/src/lib/components/arcane-table/arcane-table.svelte
@@ -432,11 +432,19 @@
}
});
- // Memoize column definitions - only rebuild when structure changes
- // Generate a key based on column structure, not data
+ // Memoize column definitions until their structure or facet options change.
+ // Facet catalogs can arrive after the table's first render, so their metadata
+ // must participate in the key even though row data does not.
function getColumnsKey(specs: ColumnSpec<TData>[], hasRowActions: boolean, isSelectionDisabled: boolean): string {
- const colIds = specs.map((s, i) => s.id ?? s.accessorKey ?? `col_${i}`).join(',');
- return `${colIds}:${hasRowActions}:${isSelectionDisabled}`;
+ const columnsMetadata = specs.map((spec, index) => ({
+ id: spec.id ?? spec.accessorKey ?? `col_${index}`,
+ filterOptions: spec.filterOptions?.map((option) => ({
+ value: option.value,
+ label: option.label,
+ dotClass: option.dotClass
+ }))
+ }));
+ return `${JSON.stringify(columnsMetadata)}:${hasRowActions}:${isSelectionDisabled}`;
}
const columnsKey = $derived(getColumnsKey(columns, !!rowActions, selectionDisabled));
diff --git a/frontend/src/lib/components/code-editor/analysis/compose-schema.ts b/frontend/src/lib/components/code-editor/analysis/compose-schema.ts
index e374b2c4a..63d8a62b1 100644
--- a/frontend/src/lib/components/code-editor/analysis/compose-schema.ts
+++ b/frontend/src/lib/components/code-editor/analysis/compose-schema.ts
@@ -30,7 +30,7 @@ const ARCANE_ROOT_EXTENSION_COMPLETIONS: ArcaneCompletionSpec[] = [
{
label: 'x-arcane',
detail: 'Arcane extension',
- info: 'Arcane compose metadata block for project-level theme icons and URLs.'
+ info: 'Arcane compose metadata block for project-level theme icons, URLs, and tags.'
}
];
@@ -54,6 +54,11 @@ const ARCANE_BLOCK_COMPLETIONS: ArcaneCompletionSpec[] = [
label: 'urls',
detail: 'Arcane project URLs',
info: 'Additional project URLs (for example docs or homepage links).'
+ },
+ {
+ label: 'tags',
+ detail: 'Arcane project tags',
+ info: 'A tag or list of tags used to group and filter projects. Compose-defined tags are read-only in Arcane.'
}
];
@@ -83,6 +88,21 @@ const ARCANE_SERVICE_BLOCK_COMPLETIONS: ArcaneCompletionSpec[] = [
}
];
+const ARCANE_TAG_COMPLETIONS: ArcaneCompletionSpec[] = [
+ {
+ label: 'name',
+ detail: 'Arcane project tag name',
+ info: 'Normalized project tag name used for grouping and filtering.'
+ },
+ {
+ label: 'color',
+ detail: 'Arcane project tag color',
+ info: 'Tag color: gray, purple, blue, green, yellow, orange, red, or pink.'
+ }
+];
+
+const ARCANE_TAG_COLORS = ['gray', 'purple', 'blue', 'green', 'yellow', 'orange', 'red', 'pink'];
+
function asSchemaObject(value: unknown): SchemaObject | null {
if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
return value as SchemaObject;
@@ -306,6 +326,8 @@ function getArcaneCompletionOptionsForPath(path: Array<string | number>, prefix
specs = ARCANE_SERVICE_EXTENSION_COMPLETIONS;
} else if (isServiceArcanePath(path)) {
specs = ARCANE_SERVICE_BLOCK_COMPLETIONS;
+ } else if (path.length === 3 && path[0] === 'x-arcane' && path[1] === 'tags' && typeof path[2] === 'number') {
+ specs = ARCANE_TAG_COMPLETIONS;
}
return specs
@@ -318,7 +340,7 @@ function getArcaneSchemaDocForPath(path: Array<string | number>): SchemaDoc | nu
if (path.length === 1 && path[0] === 'x-arcane') {
return {
title: 'x-arcane',
- description: 'Arcane extension block for project-level metadata such as theme icons and custom URLs.'
+ description: 'Arcane extension block for project-level metadata such as theme icons, custom URLs, and tags.'
};
}
@@ -350,6 +372,29 @@ function getArcaneSchemaDocForPath(path: Array<string | number>): SchemaDoc | nu
};
}
+ if (path.length === 2 && path[0] === 'x-arcane' && path[1] === 'tags') {
+ return {
+ title: 'x-arcane.tags',
+ description:
+ 'A list of project tag objects. Each tag requires a name and color and is read-only in Arcane while defined here.',
+ examples: ['[{ name: database, color: purple }]']
+ };
+ }
+
+ if (path.length === 4 && path[0] === 'x-arcane' && path[1] === 'tags' && typeof path[2] === 'number' && path[3] === 'name') {
+ return {
+ title: 'x-arcane.tags[].name',
+ description: 'Required tag name. Names are trimmed, normalized to lowercase, and limited to 64 characters.'
+ };
+ }
+
+ if (path.length === 4 && path[0] === 'x-arcane' && path[1] === 'tags' && typeof path[2] === 'number' && path[3] === 'color') {
+ return {
+ title: 'x-arcane.tags[].color',
+ description: 'Required tag color: gray, purple, blue, green, yellow, orange, red, or pink.'
+ };
+ }
+
if (path.length === 3 && path[0] === 'services' && typeof path[1] === 'string' && path[2] === 'x-arcane') {
return {
title: 'services.<name>.x-arcane',
@@ -463,17 +508,21 @@ export function getCompletionOptionsForPath(
}
export function getEnumValueCompletions(schema: SchemaObject | null, path: Array<string | number>): Completion[] {
- if (!schema) return [];
- const candidates = getPathCandidates(schema, path);
const values = new Set<string>();
+ if (path.length === 4 && path[0] === 'x-arcane' && path[1] === 'tags' && typeof path[2] === 'number' && path[3] === 'color') {
+ for (const color of ARCANE_TAG_COLORS) values.add(color);
+ }
- for (const candidate of candidates) {
- const expanded = expandCandidates(schema, candidate, new Set<string>());
- for (const node of expanded) {
- if (!Array.isArray(node['enum'])) continue;
- for (const value of node['enum']) {
- if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
- values.add(String(value));
+ if (schema) {
+ const candidates = getPathCandidates(schema, path);
+ for (const candidate of candidates) {
+ const expanded = expandCandidates(schema, candidate, new Set<string>());
+ for (const node of expanded) {
+ if (!Array.isArray(node['enum'])) continue;
+ for (const value of node['enum']) {
+ if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+ values.add(String(value));
+ }
}
}
}
diff --git a/frontend/src/lib/components/project-tag-editor.svelte b/frontend/src/lib/components/project-tag-editor.svelte
new file mode 100644
index 000000000..cec679389
--- /dev/null
+++ b/frontend/src/lib/components/project-tag-editor.svelte
@@ -0,0 +1,213 @@
+<script lang="ts">
+ import type { ProjectTag, ProjectTagColor, ProjectTagOption } from '#lib/types/swarm';
+ import * as Command from '#lib/components/ui/command';
+ import * as Popover from '#lib/components/ui/popover';
+ import * as Select from '#lib/components/ui/select';
+ import { Badge } from '#lib/components/ui/badge';
+ import { AddIcon, CheckIcon, LockIcon } from '#lib/icons';
+ import { m } from '#lib/paraglide/messages';
+ import { toast } from 'svelte-sonner';
+ import { mergeProps } from 'bits-ui';
+
+ let {
+ tags = $bindable([]),
+ availableTags = [],
+ canEdit = true,
+ maxVisible = 3,
+ onToggle,
+ class: className = ''
+ }: {
+ tags?: ProjectTag[];
+ availableTags?: ProjectTagOption[];
+ canEdit?: boolean;
+ maxVisible?: number;
+ onToggle?: (name: string, attached: boolean, color: ProjectTagColor) => Promise<ProjectTag[] | void> | ProjectTag[] | void;
+ class?: string;
+ } = $props();
+
+ let search = $state('');
+ let pending = $state<string | null>(null);
+ let selectedColor = $state<ProjectTagColor>('gray');
+ const normalizedSearch = $derived(normalizeTagInternal(search));
+ const visibleTags = $derived(tags.slice(0, maxVisible));
+ const overflow = $derived(Math.max(tags.length - maxVisible, 0));
+ const options = $derived.by(() => {
+ const byName = new Map<string, ProjectTagOption>();
+ for (const tag of availableTags) {
+ const name = normalizeTagInternal(tag.name);
+ if (name) byName.set(name, { name, color: tag.color ?? 'gray' });
+ }
+ for (const tag of tags) {
+ byName.set(tag.name, { name: tag.name, color: tag.color ?? 'gray' });
+ }
+ return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+ });
+ const canCreate = $derived(
+ canEdit &&
+ normalizedSearch.length > 0 &&
+ isValidTagInternal(normalizedSearch) &&
+ !options.some((option) => option.name === normalizedSearch)
+ );
+ const colorOptions = $derived([
+ { value: 'gray' as const, label: m.project_tags_color_gray() },
+ { value: 'purple' as const, label: m.project_tags_color_purple() },
+ { value: 'blue' as const, label: m.project_tags_color_blue() },
+ { value: 'green' as const, label: m.project_tags_color_green() },
+ { value: 'yellow' as const, label: m.project_tags_color_yellow() },
+ { value: 'orange' as const, label: m.project_tags_color_orange() },
+ { value: 'red' as const, label: m.project_tags_color_red() },
+ { value: 'pink' as const, label: m.project_tags_color_pink() }
+ ]);
+
+ function normalizeTagInternal(value: string): string {
+ return value.trim().toLowerCase();
+ }
+
+ function isValidTagInternal(value: string): boolean {
+ return (
+ value.length > 0 && Array.from(value).length <= 64 && !value.includes(',') && !/[\u0000-\u001f\u007f-\u009f]/u.test(value)
+ );
+ }
+
+ function isComposeTagInternal(tag: ProjectTag | undefined): boolean {
+ return tag?.sources.includes('compose') ?? false;
+ }
+
+ function tagColorClassInternal(color: ProjectTagColor | undefined): string {
+ switch (color) {
+ case 'purple':
+ return 'bg-violet-500';
+ case 'blue':
+ return 'bg-blue-500';
+ case 'green':
+ return 'bg-emerald-500';
+ case 'yellow':
+ return 'bg-amber-400';
+ case 'orange':
+ return 'bg-orange-500';
+ case 'red':
+ return 'bg-red-500';
+ case 'pink':
+ return 'bg-pink-500';
+ default:
+ return 'bg-zinc-400';
+ }
+ }
+
+ async function toggleTagInternal(name: string, color: ProjectTagColor = 'gray') {
+ const normalized = normalizeTagInternal(name);
+ if (!canEdit || !isValidTagInternal(normalized) || pending) return;
+ const existing = tags.find((tag) => tag.name === normalized);
+ if (isComposeTagInternal(existing)) return;
+
+ const previous = tags;
+ const attached = !existing;
+ const resolvedColor = existing?.color ?? color;
+ tags = attached
+ ? [...tags, { name: normalized, color: resolvedColor, sources: ['ui'] } satisfies ProjectTag].sort((a, b) =>
+ a.name.localeCompare(b.name)
+ )
+ : tags.filter((tag) => tag.name !== normalized);
+ pending = normalized;
+ try {
+ const updated = await onToggle?.(normalized, attached, resolvedColor);
+ if (updated) tags = updated;
+ search = '';
+ selectedColor = 'gray';
+ } catch (error) {
+ tags = previous;
+ toast.error(error instanceof Error ? error.message : m.common_error());
+ } finally {
+ pending = null;
+ }
+ }
+</script>
+
+<Popover.Root>
+ <Popover.Trigger>
+ {#snippet child({ props })}
+ {@const triggerProps = mergeProps(props, {
+ onclick: (event: MouseEvent) => event.stopPropagation()
+ })}
+ <button {...triggerProps} type="button" class="flex min-h-7 max-w-full items-center gap-1 text-left {className}">
+ {#each visibleTags as tag (tag.name)}
+ <Badge
+ variant={isComposeTagInternal(tag) ? 'gray' : 'outline'}
+ size="sm"
+ title={isComposeTagInternal(tag) ? m.project_tags_defined_in_compose() : undefined}
+ >
+ <span class="size-2 shrink-0 rounded-full {tagColorClassInternal(tag.color)}"></span>
+ {tag.name}
+ {#if isComposeTagInternal(tag)}<LockIcon class="size-3" />{/if}
+ </Badge>
+ {/each}
+ {#if overflow > 0}<Badge variant="gray" size="sm">+{overflow}</Badge>{/if}
+ {#if canEdit}<AddIcon class="size-4 shrink-0 text-muted-foreground" aria-label={m.project_tags_add()} />{/if}
+ </button>
+ {/snippet}
+ </Popover.Trigger>
+ <Popover.Content class="w-72 p-0" align="start" onclick={(event) => event.stopPropagation()}>
+ <Command.Root class="rounded-none bg-transparent">
+ <Command.Input bind:value={search} placeholder={m.project_tags_search()} />
+ <Command.List>
+ <Command.Empty class={canCreate ? 'px-4 py-5' : undefined}>
+ {#if canCreate}
+ <div class="flex flex-col items-center gap-4">
+ <p class="leading-snug">
+ {m.project_tags_create_prompt()}<br />
+ <span class="font-medium">“{normalizedSearch}”</span>
+ </p>
+ <div class="flex items-center gap-2">
+ <Select.Root type="single" bind:value={selectedColor}>
+ <Select.Trigger class="h-9 min-w-28 bg-background">
+ <span class="block size-2.5 shrink-0 rounded-full {tagColorClassInternal(selectedColor)}"></span>
+ {colorOptions.find((option) => option.value === selectedColor)?.label}
+ </Select.Trigger>
+ <Select.Content>
+ {#each colorOptions as option (option.value)}
+ <Select.Item value={option.value}>
+ <span class="block size-2.5 shrink-0 rounded-full {tagColorClassInternal(option.value)}"></span>
+ {option.label}
+ </Select.Item>
+ {/each}
+ </Select.Content>
+ </Select.Root>
+ <button
+ type="button"
+ class="h-9 rounded-md border border-input bg-background px-3 text-sm font-medium shadow-xs hover:bg-accent disabled:opacity-50"
+ disabled={pending !== null}
+ onclick={(event) => {
+ event.stopPropagation();
+ void toggleTagInternal(normalizedSearch, selectedColor);
+ }}
+ >
+ {m.common_create()}
+ </button>
+ </div>
+ </div>
+ {:else}
+ {m.common_no_results_found()}
+ {/if}
+ </Command.Empty>
+ <Command.Group>
+ {#each options as option (option.name)}
+ {@const tag = tags.find((item) => item.name === option.name)}
+ {@const locked = isComposeTagInternal(tag)}
+ <Command.Item
+ disabled={!canEdit || locked || pending !== null}
+ onSelect={() => toggleTagInternal(option.name, option.color)}
+ title={locked ? m.project_tags_defined_in_compose() : undefined}
+ >
+ <span class="flex size-4 items-center justify-center rounded-sm border">
+ {#if tag}<CheckIcon class="size-4" />{/if}
+ </span>
+ <span class="size-2.5 shrink-0 rounded-full {tagColorClassInternal(option.color)}"></span>
+ <span class="min-w-0 flex-1 truncate">{option.name}</span>
+ {#if locked}<LockIcon class="size-4" /><span class="sr-only">{m.project_tags_defined_in_compose()}</span>{/if}
+ </Command.Item>
+ {/each}
+ </Command.Group>
+ </Command.List>
+ </Command.Root>
+ </Popover.Content>
+</Popover.Root>
diff --git a/frontend/src/lib/query/query-keys.ts b/frontend/src/lib/query/query-keys.ts
index ee5a0bd4d..a092fb691 100644
--- a/frontend/src/lib/query/query-keys.ts
+++ b/frontend/src/lib/query/query-keys.ts
@@ -115,6 +115,7 @@ export const queryKeys = {
detailCheckUpdates: (environmentId: string, projectId: string) =>
['project', 'check-updates', environmentId, projectId] as const,
statusCounts: (environmentId: string) => ['projects', 'status-counts', environmentId] as const,
+ tags: (environmentId: string) => ['projects', 'tags', environmentId] as const,
detail: (environmentId: string, projectId: string) => ['project', environmentId, projectId] as const,
workspace: (environmentId: string, projectId: string) => ['project', environmentId, projectId, 'workspace'] as const,
workspaceFile: (environmentId: string, projectId: string, relativePath: string) =>
diff --git a/frontend/src/lib/services/project-service.ts b/frontend/src/lib/services/project-service.ts
index b76c2175e..fc8878255 100644
--- a/frontend/src/lib/services/project-service.ts
+++ b/frontend/src/lib/services/project-service.ts
@@ -1,7 +1,7 @@
import { m } from '#lib/paraglide/messages';
import { environmentStore } from '#lib/stores/environment.store.svelte';
import type { Paginated, SearchPaginationSortRequest } from '#lib/types/shared';
-import type { Project, ProjectStatusCounts } from '#lib/types/swarm';
+import type { Project, ProjectStatusCounts, ProjectTag, ProjectTagColor, ProjectTagOption } from '#lib/types/swarm';
import type { ProjectWorkspaceFileDraft } from '#lib/types/project-workspace';
import { readNdjsonStream } from '#lib/utils/streaming';
import { transformPaginationParams } from '#lib/utils/tables';
@@ -59,7 +59,8 @@ class ProjectService extends BaseAPIService {
projectName: string,
composeContent: string,
envContent?: string,
- workspaceFiles: ProjectWorkspaceFileDraft[] = []
+ workspaceFiles: ProjectWorkspaceFileDraft[] = [],
+ tags: ProjectTag[] = []
): Promise<Project> {
const envId = await environmentStore.getCurrentEnvironmentId();
const form = new FormData();
@@ -70,7 +71,16 @@ class ProjectService extends BaseAPIService {
uploads.push(new File([file.content ?? ''], file.relativePath));
return { operation: 'create_file' as const, relativePath: file.relativePath, uploadIndex };
});
- form.append('project', JSON.stringify({ name: projectName, composeContent, envContent }));
+ form.append(
+ 'project',
+ JSON.stringify({
+ name: projectName,
+ composeContent,
+ envContent,
+ tags: tags.map((tag) => tag.name),
+ tagColors: Object.fromEntries(tags.map((tag) => [tag.name, tag.color]))
+ })
+ );
form.append('manifest', JSON.stringify({ fileChanges }));
for (const file of uploads) form.append('files', file, file.name);
return this.handleResponse(this.api.post(`/environments/${envId}/projects`, form));
@@ -147,6 +157,20 @@ class ProjectService extends BaseAPIService {
return res.data.data;
}
+ async getProjectTagsForEnvironment(environmentId: string): Promise<ProjectTagOption[]> {
+ return this.handleResponse(this.api.get(`/environments/${environmentId}/projects/tags`));
+ }
+
+ async updateProjectTag(
+ projectId: string,
+ name: string,
+ attached: boolean,
+ color?: ProjectTagColor
+ ): Promise<{ tags: ProjectTag[]; activityId?: string }> {
+ const envId = await environmentStore.getCurrentEnvironmentId();
+ return this.handleResponse(this.api.patch(`/environments/${envId}/projects/${projectId}/tags`, { name, attached, color }));
+ }
+
async updateProject(
projectId: string,
name?: string,
diff --git a/frontend/src/lib/types/swarm.ts b/frontend/src/lib/types/swarm.ts
index 11101f63e..693ff99cc 100644
--- a/frontend/src/lib/types/swarm.ts
+++ b/frontend/src/lib/types/swarm.ts
@@ -582,6 +582,20 @@ export interface ProjectUpdateInfo {
lastCheckedAt?: string;
}
+export type ProjectTagSource = 'ui' | 'compose';
+export type ProjectTagColor = 'gray' | 'purple' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'pink';
+
+export interface ProjectTag {
+ name: string;
+ color: ProjectTagColor;
+ sources: ProjectTagSource[];
+}
+
+export interface ProjectTagOption {
+ name: string;
+ color: ProjectTagColor;
+}
+
export interface Project {
id: string;
name: string;
@@ -591,6 +605,7 @@ export interface Project {
iconLightUrl?: string;
iconDarkUrl?: string;
urls?: string[];
+ tags?: ProjectTag[];
runningCount: string;
serviceCount: string;
status: string;
diff --git a/frontend/src/lib/utils/tables.ts b/frontend/src/lib/utils/tables.ts
index 763bc35fa..5e1eb4c23 100644
--- a/frontend/src/lib/utils/tables.ts
+++ b/frontend/src/lib/utils/tables.ts
@@ -32,14 +32,14 @@ function buildFilterMap(pairs?: [string, unknown][]): FilterMap {
for (const [id, rawValue] of pairs) {
let value: unknown = rawValue;
if (value instanceof Set) {
- const iterator = value.values().next();
- value = iterator.value;
+ value = Array.from(value);
}
if (Array.isArray(value)) {
- const first = value.find((entry) => entry !== undefined && entry !== null && `${entry}`.trim() !== '');
- if (first === undefined) continue;
- value = first;
+ const entries = value.filter((entry) => entry !== undefined && entry !== null && `${entry}`.trim() !== '');
+ if (entries.length === 0) continue;
+ filters[id] = entries as FilterValue;
+ continue;
}
if (value === undefined || value === null) continue;
diff --git a/frontend/src/routes/(app)/projects/+page.svelte b/frontend/src/routes/(app)/projects/+page.svelte
index 1a9641a2b..6be1998fc 100644
--- a/frontend/src/routes/(app)/projects/+page.svelte
+++ b/frontend/src/routes/(app)/projects/+page.svelte
@@ -70,6 +70,17 @@
refetchOnMount: false
};
});
+ const projectTagsQuery = createQuery(() => {
+ const queryEnvId = envId;
+ return {
+ queryKey: queryKeys.projects.tags(queryEnvId),
+ queryFn: () => projectService.getProjectTagsForEnvironment(queryEnvId),
+ initialData: data.envId === queryEnvId ? data.projectTags : undefined,
+ select: (value) => ({ envId: queryEnvId, value }),
+ refetchOnMount: false
+ };
+ });
+ const projectTags = $derived(projectTagsQuery.data?.envId === envId ? projectTagsQuery.data.value : []);
const resourcesReady = $derived(projects !== null);
$effect(() => {
@@ -251,6 +262,7 @@
bind:selectedIds
requestOptions={projectRequestOptions}
{showArchived}
+ availableTags={projectTags}
onToggleArchived={toggleArchived}
onRefreshData={async (options) => {
const requestedEnvId = envId;
diff --git a/frontend/src/routes/(app)/projects/+page.ts b/frontend/src/routes/(app)/projects/+page.ts
index 67e34072f..9dd1b9933 100644
--- a/frontend/src/routes/(app)/projects/+page.ts
+++ b/frontend/src/routes/(app)/projects/+page.ts
@@ -31,8 +31,9 @@ export const load: PageLoad = async ({ parent, url }) => {
let projects;
let projectStatusCounts;
+ let projectTags;
try {
- [projects, projectStatusCounts] = await Promise.all([
+ [projects, projectStatusCounts, projectTags] = await Promise.all([
queryClient.fetchQuery({
queryKey: queryKeys.projects.list(envId, projectRequestOptions),
queryFn: () => projectService.getProjectsForEnvironment(envId, projectRequestOptions)
@@ -40,11 +41,15 @@ export const load: PageLoad = async ({ parent, url }) => {
queryClient.fetchQuery({
queryKey: queryKeys.projects.statusCounts(envId),
queryFn: () => projectService.getProjectStatusCountsForEnvironment(envId)
+ }),
+ queryClient.fetchQuery({
+ queryKey: queryKeys.projects.tags(envId),
+ queryFn: () => projectService.getProjectTagsForEnvironment(envId)
})
]);
} catch (err) {
throwPageLoadError(err, 'Failed to load projects');
}
- return { envId, projects, projectRequestOptions, projectStatusCounts, showArchived };
+ return { envId, projects, projectRequestOptions, projectStatusCounts, projectTags, showArchived };
};
diff --git a/frontend/src/routes/(app)/projects/[projectId]/+page.svelte b/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
index 38b30263b..1313f668b 100644
--- a/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
+++ b/frontend/src/routes/(app)/projects/[projectId]/+page.svelte
@@ -1,5 +1,5 @@
<script lang="ts">
- import type { IncludeFile, Project } from '#lib/types/swarm';
+ import type { IncludeFile, Project, ProjectTagColor, ProjectTagOption } from '#lib/types/swarm';
import type { ProjectWorkspaceFileChange, ProjectWorkspaceFileContent } from '#lib/types/project-workspace';
import * as Tabs from '#lib/components/ui/tabs/index.js';
import * as Alert from '#lib/components/ui/alert/index.js';
@@ -61,6 +61,7 @@
import IconImage from '#lib/components/icon-image.svelte';
import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query';
import ProjectUpdateItem from '#lib/components/project-update-item.svelte';
+ import ProjectTagEditor from '#lib/components/project-tag-editor.svelte';
import IfPermitted from '#lib/components/if-permitted.svelte';
import { activityToastOptions, extractActivityId } from '#lib/utils/activity-toast';
import { globalVariablesToMap } from '#lib/utils/template-load';
@@ -128,6 +129,26 @@
initialData: data.project,
refetchOnMount: false
}));
+ const projectTagsQuery = createQuery(() => ({
+ queryKey: queryKeys.projects.tags(envId),
+ queryFn: () => projectService.getProjectTagsForEnvironment(envId)
+ }));
+ const availableProjectTags = $derived(projectTagsQuery.data ?? []);
+
+ async function handleProjectTagToggle(name: string, attached: boolean, color: ProjectTagColor) {
+ const response = await projectService.updateProjectTag(projectId, name, attached, color);
+ queryClient.setQueryData<Project>(queryKeys.projects.detail(envId, projectId), (current) =>
+ current ? { ...current, tags: response.tags } : current
+ );
+ if (attached) {
+ queryClient.setQueryData<ProjectTagOption[]>(queryKeys.projects.tags(envId), (current = []) =>
+ current.some((tag) => tag.name === name)
+ ? current
+ : [...current, { name, color }].sort((a, b) => a.name.localeCompare(b.name))
+ );
+ }
+ return response.tags;
+ }
// The workspace walk can be slow on large projects, so it loads lazily and
// never blocks navigation; +page.ts prefetches this key without awaiting.
@@ -1359,6 +1380,12 @@
{#if project.isArchived}
<Badge variant="gray" minWidth="20">{m.projects_archived_badge()}</Badge>
{/if}
+ <ProjectTagEditor
+ tags={project.tags ?? []}
+ availableTags={availableProjectTags}
+ canEdit={canUpdateProject}
+ onToggle={handleProjectTagToggle}
+ />
<ProjectUpdateItem
updateInfo={project.updateInfo}
onCheck={handleCheckProjectUpdates}
diff --git a/frontend/src/routes/(app)/projects/new/+page.svelte b/frontend/src/routes/(app)/projects/new/+page.svelte
index 34541c676..4b57bf5b4 100644
--- a/frontend/src/routes/(app)/projects/new/+page.svelte
+++ b/frontend/src/routes/(app)/projects/new/+page.svelte
@@ -22,6 +22,10 @@
import { activityToastOptions, extractActivityId } from '#lib/utils/activity-toast';
import { globalVariablesToMap } from '#lib/utils/template-load';
import type { ProjectWorkspaceFileDraft } from '#lib/types/project-workspace';
+ import type { ProjectTag } from '#lib/types/swarm';
+ import ProjectTagEditor from '#lib/components/project-tag-editor.svelte';
+ import { createQuery } from '@tanstack/svelte-query';
+ import { queryKeys } from '#lib/query/query-keys';
import settingsStore from '#lib/stores/config-store';
import {
planProjectWorkspaceFileCreate,
@@ -88,6 +92,12 @@
let selectedEditorFile = $state<'compose' | 'env' | string>('compose');
let treePaneWidth = $state(280);
let newProjectWorkspaceFiles = $state<ProjectWorkspaceFileDraft[]>([]);
+ let newProjectTags = $state<ProjectTag[]>([]);
+ const projectTagsQuery = createQuery(() => ({
+ queryKey: queryKeys.projects.tags(currentEnvId),
+ queryFn: () => projectService.getProjectTagsForEnvironment(currentEnvId)
+ }));
+ const availableProjectTags = $derived(projectTagsQuery.data ?? []);
let newProjectWorkspaceContents = $state<Record<string, string>>({});
let newProjectWorkspaceHasErrors = $state<Record<string, boolean>>({});
let newProjectWorkspaceValidationReady = $state<Record<string, boolean>>({});
@@ -193,7 +203,7 @@
validate: () => validateTemplateEditorForm(validationState, form.validate),
setLoading: (value) => (ui.saving = value),
submit: ({ name, composeContent, envContent }) =>
- projectService.createProject(name, composeContent, envContent, buildNewProjectWorkspacePayload()),
+ projectService.createProject(name, composeContent, envContent, buildNewProjectWorkspacePayload(), newProjectTags),
failureMessage: (name) => m.common_create_failed({ resource: `${m.resource_project()} "${name}"` }),
onSuccess: async (project, { name }) => {
toast.success(
@@ -353,6 +363,7 @@
disabledMessage={composeYamlName ? m.compose_project_name_defined_in_yaml() : undefined}
class="hidden sm:block"
/>
+ <ProjectTagEditor bind:tags={newProjectTags} availableTags={availableProjectTags} canEdit={!ui.saving} />
</div>
</div>
@@ -415,6 +426,7 @@
canEdit={!ui.saving && !ui.isLoadingTemplateContent && !composeYamlName}
disabledMessage={composeYamlName ? m.compose_project_name_defined_in_yaml() : undefined}
/>
+ <ProjectTagEditor bind:tags={newProjectTags} availableTags={availableProjectTags} canEdit={!ui.saving} class="mt-2" />
</div>
<div class="flex shrink-0 items-center justify-end gap-2">
diff --git a/frontend/src/routes/(app)/projects/projects-table.svelte b/frontend/src/routes/(app)/projects/projects-table.svelte
index 185cc38de..cc89cf878 100644
--- a/frontend/src/routes/(app)/projects/projects-table.svelte
+++ b/frontend/src/routes/(app)/projects/projects-table.svelte
@@ -1,5 +1,5 @@
<script lang="ts">
- import type { Project } from '#lib/types/swarm';
+ import type { Project, ProjectTagColor, ProjectTagOption } from '#lib/types/swarm';
import ArcaneTable from '#lib/components/arcane-table/arcane-table.svelte';
import * as DropdownMenu from '#lib/components/ui/dropdown-menu/index.js';
import RowActionsMenu from '#lib/components/arcane-table/row-actions-menu.svelte';
@@ -27,6 +27,7 @@
import type { ActionStatus } from './projects-table.helpers';
import { createProjectActions } from './projects-table.actions';
import ProjectUpdateItem from '#lib/components/project-update-item.svelte';
+ import ProjectTagEditor from '#lib/components/project-tag-editor.svelte';
import { Label } from '#lib/components/ui/label';
import { Switch } from '#lib/components/ui/switch/index.js';
import {
@@ -43,7 +44,8 @@
withoutFilters = false,
showArchived = false,
onToggleArchived,
- onRefreshData
+ onRefreshData,
+ availableTags = []
}: {
projects: Paginated<Project>;
selectedIds: string[];
@@ -52,10 +54,15 @@
showArchived?: boolean;
onToggleArchived?: (checked: boolean) => void | Promise<void>;
onRefreshData?: (options: SearchPaginationSortRequest) => Promise<void>;
+ availableTags?: ProjectTagOption[];
} = $props();
let actionStatus = $state<Record<string, ActionStatus>>({});
let checkingProjectIds = $state<Record<string, boolean>>({});
+ let tagCatalog = $state<ProjectTagOption[]>([]);
+ $effect(() => {
+ tagCatalog = availableTags;
+ });
let isBulkLoading = $state({
up: false,
@@ -105,6 +112,18 @@
}
}
+ async function handleTagToggle(project: Project, name: string, attached: boolean, color: ProjectTagColor) {
+ const response = await projectService.updateProjectTag(project.id, name, attached, color);
+ if (attached && !tagCatalog.some((tag) => tag.name === name)) {
+ tagCatalog = [...tagCatalog, { name, color }].sort((a, b) => a.name.localeCompare(b.name));
+ }
+ projects = {
+ ...projects,
+ data: projects.data.map((item) => (item.id === project.id ? { ...item, tags: response.tags } : item))
+ };
+ return response.tags;
+ }
+
function getStatusTooltip(project: Project): string | undefined {
return project.status.toLowerCase() === 'unknown' && project.statusReason ? project.statusReason : undefined;
}
@@ -148,28 +167,39 @@
project.status === 'restarting';
const hasRunningSelection = $derived.by(() => selectedProjects.some((project) => isProjectArchiveBlocked(project)));
- const columns = [
- { accessorKey: 'id', title: m.common_id(), hidden: true },
- { accessorKey: 'name', title: m.common_name(), sortable: true, cell: NameCell },
- { accessorKey: 'path', title: m.common_working_directory(), sortable: true, cell: DirectoryCell },
- { accessorKey: 'gitOpsManagedBy', title: m.projects_col_provider(), cell: ProviderCell },
- { accessorKey: 'status', title: m.common_status(), sortable: true, cell: StatusCell },
- {
- id: 'updates',
- accessorFn: (row) => getProjectUpdateStatus(row.updateInfo),
- title: m.updates(),
- sortable: false,
- cell: UpdatesCell
- },
- { accessorKey: 'createdAt', title: m.common_created(), sortable: true, cell: CreatedCell },
- { accessorKey: 'serviceCount', title: m.services(), sortable: true }
- ] satisfies ColumnSpec<Project>[];
+ const columns = $derived.by(
+ () =>
+ [
+ { accessorKey: 'id', title: m.common_id(), hidden: true },
+ { accessorKey: 'name', title: m.common_name(), sortable: true, cell: NameCell },
+ {
+ id: 'tags',
+ accessorFn: (row) => row.tags?.map((tag) => tag.name) ?? [],
+ title: m.common_tags(),
+ cell: TagsCell,
+ filterOptions: tagCatalog.map((tag) => ({ label: tag.name, value: tag.name }))
+ },
+ { accessorKey: 'path', title: m.common_working_directory(), sortable: true, cell: DirectoryCell },
+ { accessorKey: 'gitOpsManagedBy', title: m.projects_col_provider(), cell: ProviderCell },
+ { accessorKey: 'status', title: m.common_status(), sortable: true, cell: StatusCell },
+ {
+ id: 'updates',
+ accessorFn: (row) => getProjectUpdateStatus(row.updateInfo),
+ title: m.updates(),
+ sortable: false,
+ cell: UpdatesCell
+ },
+ { accessorKey: 'createdAt', title: m.common_created(), sortable: true, cell: CreatedCell },
+ { accessorKey: 'serviceCount', title: m.services(), sortable: true }
+ ] satisfies ColumnSpec<Project>[]
+ );
const mobileFields = [
{ id: 'id', label: m.common_id(), defaultVisible: false },
{ id: 'directory', label: m.common_working_directory(), defaultVisible: true },
{ id: 'provider', label: m.projects_col_provider(), defaultVisible: true },
{ id: 'status', label: m.common_status(), defaultVisible: true },
+ { id: 'tags', label: m.common_tags(), defaultVisible: true },
{ id: 'updates', label: m.updates(), defaultVisible: true },
{ id: 'serviceCount', label: m.services(), defaultVisible: true },
{ id: 'createdAt', label: m.common_created(), defaultVisible: true }
@@ -242,6 +272,15 @@
</div>
{/snippet}
+{#snippet TagsCell({ item }: { item: Project })}
+ <ProjectTagEditor
+ tags={item.tags ?? []}
+ availableTags={tagCatalog}
+ canEdit={canUpdateProject && !item.isDiscovered}
+ onToggle={(name, attached, color) => handleTagToggle(item, name, attached, color)}
+ />
+{/snippet}
+
{#snippet DirectoryCell({ item }: { item: Project })}
<span class="block max-w-[22rem] truncate text-muted-foreground">{item.relativePath ?? item.dirName ?? item.path}</span>
{/snippet}
@@ -268,6 +307,15 @@
</span>
{/snippet}
+{#snippet TagsField(item: Project)}
+ <ProjectTagEditor
+ tags={item.tags ?? []}
+ availableTags={tagCatalog}
+ canEdit={canUpdateProject && !item.isDiscovered}
+ onToggle={(name, attached, color) => handleTagToggle(item, name, attached, color)}
+ />
+{/snippet}
+
{#snippet StatusCell({ item }: { item: Project })}
{@const statusTooltip = getStatusTooltip(item)}
{#if statusTooltip}
@@ -341,6 +389,13 @@
: null
]}
fields={[
+ {
+ label: m.common_tags(),
+ type: 'component',
+ getValue: (item: Project) => item,
+ component: TagsField,
+ show: mobileFieldVisibility['tags'] ?? true
+ },
{
label: m.common_working_directory(),
getValue: (item: Project) => item.relativePath ?? item.dirName ?? item.path,
diff --git a/types/project/project.go b/types/project/project.go
index df5569f2d..af0564a21 100644
--- a/types/project/project.go
+++ b/types/project/project.go
@@ -41,6 +41,72 @@ type CreateProject struct {
//
// Required: false
EnvContent *string `json:"envContent,omitempty"`
+
+ // Tags are UI-managed tags to attach to the new project.
+ //
+ // Required: false
+ Tags []string `json:"tags,omitempty"`
+
+ // TagColors maps normalized UI-managed tag names to their display colors.
+ //
+ // Required: false
+ TagColors map[string]TagColor `json:"tagColors,omitempty"`
+}
+
+// TagSource identifies where a project tag is managed.
+type TagSource string
+
+// TagColor identifies a supported project tag display color.
+type TagColor string
+
+const (
+ // TagSourceUI identifies a tag association managed through Arcane.
+ TagSourceUI TagSource = "ui"
+ // TagSourceCompose identifies a tag association managed through Compose metadata.
+ TagSourceCompose TagSource = "compose"
+
+ // TagColorGray is the neutral gray tag color.
+ TagColorGray TagColor = "gray"
+ // TagColorPurple is the purple tag color.
+ TagColorPurple TagColor = "purple"
+ // TagColorBlue is the blue tag color.
+ TagColorBlue TagColor = "blue"
+ // TagColorGreen is the green tag color.
+ TagColorGreen TagColor = "green"
+ // TagColorYellow is the yellow tag color.
+ TagColorYellow TagColor = "yellow"
+ // TagColorOrange is the orange tag color.
+ TagColorOrange TagColor = "orange"
+ // TagColorRed is the red tag color.
+ TagColorRed TagColor = "red"
+ // TagColorPink is the pink tag color.
+ TagColorPink TagColor = "pink"
+)
+
+// Tag is a normalized project tag and all of its effective sources.
+type Tag struct {
+ Name string `json:"name"`
+ Color TagColor `json:"color"`
+ Sources []TagSource `json:"sources"`
+}
+
+// TagOption is a reusable tag name and color returned by the tag catalog.
+type TagOption struct {
+ Name string `json:"name"`
+ Color TagColor `json:"color"`
+}
+
+// UpdateTag mutates a UI-managed tag association.
+type UpdateTag struct {
+ Name string `json:"name"`
+ Attached bool `json:"attached"`
+ Color TagColor `json:"color,omitempty"`
+}
+
+// UpdateTagResponse is returned after a project tag mutation.
+type UpdateTagResponse struct {
+ Tags []Tag `json:"tags"`
+ ActivityID *string `json:"activityId,omitempty"`
}
// UpdateProject is used to update a project.
@@ -302,10 +368,15 @@ type CreateReponse struct {
//
// Required: false
ActivityID *string `json:"activityId,omitempty"`
+
+ // Tags are the effective UI and Compose tags for the project.
+ Tags []Tag `json:"tags"`
}
// Details contains detailed information about a project.
type Details struct {
+ // Tags are the effective UI and Compose tags for the project.
+ Tags []Tag `json:"tags"`
// StatusReason provides additional information about the status.
//