feat(definition,template): add and remove charts, check-upgrade, upgrade, link-template (#157, #158)

.github/copilot-instructions.md

@@ -23,8 +23,8 @@ stackctl is a Go CLI tool (Cobra) for managing Kubernetes stack deployments. It
 | `login`/`logout`/`whoami` | top-level; supports password + OIDC loopback flow | login.go |
 | `auth` | register | login.go |
 | `stack` | list, get, create, update, deploy, stop, clean, delete, status, logs, clone, extend, values, compare, history, rollback, history-values, watch, preview, pods, recent, follow, unfollow, action (list, run, log) | stack.go; preview/pods/recent: stack_inspect.go; follow/unfollow: stack_followers.go; action: stack_action.go; TTL and stop-time helpers: ttl.go |
-| `template` | list, get, create, update, delete, clone, instantiate, quick-deploy, publish, unpublish, update-chart, versions (list, get, diff) | template.go |
-| `definition` | list, get, create, update, delete, export, import, update-chart | definition.go |
+| `template` | list, get, create, update, delete, clone, instantiate, quick-deploy, publish, unpublish, update-chart, add-chart, remove-chart, versions (list, get, diff) | template.go; add-chart/remove-chart: chart_changes.go |
+| `definition` | list, get, create, update, delete, export, import, update-chart, add-chart, remove-chart, check-upgrade, upgrade, link-template | definition.go; add-chart/remove-chart/check-upgrade/upgrade/link-template: chart_changes.go |
 | `override` | list, get, set, unset, delete, branch (list/set/delete), quota (get/set/delete) | override.go |
 | `bulk` | deploy, stop, clean, delete, template (publish, unpublish, delete) | bulk.go |
 | `git` | providers, branches, validate | git.go |

CLAUDE.md

@@ -35,6 +35,7 @@ cli/                          # Go module root (github.com/omattsson/stackctl/cl
     server.go                 # server info (ping, ui-config; public routes, no credentials)
     template.go               # template list/get/create/update/clone/publish/unpublish/versions/instantiate/quick-deploy/delete
     definition.go             # definition list/get/create/update/delete/export/import/update-chart
+    chart_changes.go          # definition add-chart/remove-chart/check-upgrade/upgrade/link-template, template add-chart/remove-chart
     override.go               # override list/get/set/unset/delete, branch overrides, quota overrides (quota set merges with GET, --replace)
     bulk.go                   # bulk deploy/stop/clean/delete, bulk template publish/unpublish/delete (--ids flag or positional args)
     git.go                    # git providers/branches/validate
@@ -187,8 +188,12 @@ All API calls go to `/api/v1/*`. Key route groups:
 - `/api/v1/admin/orphaned-namespaces` — `orphaned list [--details]`; `DELETE /:ns?confirm=<ns>` is needed for a namespace without the label managed-by=k8s-stack-manager (409 without it; `orphaned delete --confirm`). `test/contract/path_contract_test.go` checks every `/api/v1` literal of `pkg/client` and `cmd` against the vendored swagger
 - `/api/v1/notifications/preferences` — `notification prefs set` warns for an event type not in `notificationEventTypes` (`notifier.AllEventTypes()` of k8s-stack-manager); v0.8.0+ servers return 400
 - `/api/v1/stack-definitions` — CRUD + export/import
+  - `POST /:id/charts` and `DELETE /:id/charts/:chartId` (devops or admin; `definition add-chart`, `remove-chart`). A linked definition cannot lose a chart that the template requires (409 "Cannot delete required chart: X").
+  - `GET /:id/check-upgrade` sends only `{"upgrade_available": false}` when there is no upgrade (no source template, unpublished template, latest version). `printUpgradeCheck` reads the definition (`source_template_id`, `source_template_version`) for the reason. The server marks a chart `modified` only for other default values or another repository URL; the table also marks a chart with `has_differences` in `chart_diffs` as modified.
+  - `POST /:id/upgrade` (owner, devops or admin) replaces the default values of the template charts. `definition upgrade` shows the check on stderr and confirms unless `--yes`. 409 "Definition is already at the latest version" or "Template has no published version".
+  - `PUT /:id/template-link` `{"template_id","version"}` (k8s-stack-manager v0.11.0+, devops or admin; empty `template_id` removes the link). A plain 404 (no route) maps to the v0.11.0 upgrade hint (`linkTemplateError`).
 - `/api/v1/templates` — list/get/instantiate/quick-deploy/publish/versions
-  - Draft and release (k8s-stack-manager v0.6.0+): `PUT /:id` and the template chart routes change only the working copy. Users, quick deploy, instantiate and definition upgrades get the latest release. After `template update-chart`, run `template publish <name|id> --version <new>` so users get the change.
+  - Draft and release (k8s-stack-manager v0.6.0+): `PUT /:id` and the template chart routes change only the working copy. `POST /:id/charts` and `DELETE /:id/charts/:chartId` (`template add-chart`, `remove-chart`) write a note to stderr: publish with a new `--version` (the working-copy version already exists after a change). Users, quick deploy, instantiate and definition upgrades get the latest release. After `template update-chart`, run `template publish <name|id> --version <new>` so users get the change.
   - `POST /:id/publish` takes an optional body `{"version", "change_summary"}`; `template publish` sends it only when `--version` or `--change-summary` is set. Without a version the server uses the working-copy version. 409 "Version x already exists" and 400 "Version is required to publish" map to messages with the next command. 200 with `snapshot_created: false` prints "No changes since version X; no new version created". With `--version` or `--change-summary`, the command first does GET `/:id`; when `has_unpublished_changes` is absent (older server, which ignores the body) it fails with the v0.6.0 upgrade hint before the publish.
   - `PUT /:id`: v0.6.0+ changes only the fields sent (`PatchTemplateRequest`, pointer fields; `""` clears); older servers replace name/description/category/version/default_branch. `template update` does GET first: with `has_unpublished_changes` present it sends only the changed fields, else the full record (`UpdateTemplateRequest`). `--version` sets the working-copy version; `--description ""` clears.
   - Name resolution (`resolveTemplateID`, used by `template publish` and bulk template commands): sends `?name=` (v0.5.0 ignores it), pages through the result with `pageSize=100`, and matches the exact name on the client. 0 → not found; more than 1 → "multiple templates named X: <ids>".

README.md

@@ -346,6 +346,11 @@ stackctl template update-chart 8c9d0e1f-2a3b-4c5d-9e6f-7a8b9c0d1e2f 3f2b8c1e-5a4
 stackctl template update-chart 8c9d0e1f-2a3b-4c5d-9e6f-7a8b9c0d1e2f 3f2b8c1e-5a4d-4e6f-9a7b-1c2d3e4f5a6b --file values.yaml --locked-file locked.yaml
 stackctl template update-chart 8c9d0e1f-2a3b-4c5d-9e6f-7a8b9c0d1e2f 3f2b8c1e-5a4d-4e6f-9a7b-1c2d3e4f5a6b --build-pipeline-id 42
 
+# Add or remove a chart of the working copy (template name or ID; chart name or ID)
+stackctl template add-chart my-template --name worker --repository-url oci://registry.example.com/helm --chart-version 1.2.0
+stackctl template add-chart my-template --name api --chart-path /charts/api --required --locked-file locked.yaml
+stackctl template remove-chart my-template worker
+
 # Release the working copy to users (name or ID)
 stackctl template publish my-template --version 1.2.0 --change-summary "app-core chart 0.3.7"
 
@@ -365,7 +370,7 @@ Most template commands need the template ID. `template publish` accepts a name o
 
 Templates use a draft-and-release model:
 
-- `template update` and `template update-chart` change only the working copy (draft).
+- `template update`, `template update-chart`, `template add-chart` and `template remove-chart` change only the working copy (draft). `add-chart` and `remove-chart` write a note to stderr: run `template publish` so users get the change.
 - Users get the latest released version. Quick deploy, instantiate and definition upgrades use it.
 - After `template update-chart`, run `stackctl template publish <name|id> --version <new-version>` so users get the change.
 - Each version can be released only once. Publish without changes creates no new version.
@@ -397,6 +402,18 @@ stackctl definition update-chart example-dev my-chart --deploy-order 6
 stackctl definition update-chart example-dev my-chart --file values.yaml
 stackctl definition update-chart example-dev my-chart --build-pipeline-id 42
 
+# Add or remove a chart (devops or admin; remove-chart asks for confirmation unless --yes)
+stackctl definition add-chart example-dev --name worker --repository-url oci://registry.example.com/helm --chart-version 1.2.0
+stackctl definition remove-chart example-dev worker
+
+# Upgrade to the latest published version of the source template
+stackctl definition check-upgrade example-dev
+stackctl definition upgrade example-dev           # shows the changes, then asks for confirmation (--yes skips it)
+
+# Link a definition to a published template version, or remove the link (devops or admin)
+stackctl definition link-template example-dev --template web-stack --version 1.2.0
+stackctl definition link-template example-dev --unlink
+
 # Delete
 stackctl definition delete example-dev
 
@@ -598,6 +615,7 @@ These groups have no section above. Run `stackctl <group> --help` for the flags.
 | `stack extend --minutes`, template draft and release, `template publish --version` | v0.6.0 or later |
 | Owner, cluster and definition names in output, audit action and entity type values, paged `--mine` and name queries, quota override limit check, quota warning on `stack clone` | v0.7.0 or later |
 | `--follow` and `stack watch` with an API key, `bulk delete` with clean first, `orphaned delete --confirm`, `user set-role` | v0.8.0 or later |
+| `definition link-template` | v0.11.0 or later |
 | `--stop-at`, `stack extend --until`, the TTL limit of `server info` and of the local check (an older server ignores `--stop-at` and `--until`: stackctl shows the result and exits with code 1; it uses 30 days as the limit) | v0.12.0 or later |
 
 ## Output Formats