proposal: deployah use / project for sticky context and namespace

[atkrad]

Problem

Day-to-day work needs a sticky default target. OpenShift users get that with oc project <name> (updates the current kubeconfig context's namespace). Kubernetes users use kubectx / kubens.

With Deployah you must pass -n / --context every time, or rely on kubeconfig current context when the platform entry has no context. That is easy to get wrong across local kind + remote clusters, and it does not map cleanly to Deployah environments (local, staging, prod), which already encode the intended context in the platform file.

Goals

• A first-class command to show and switch the active target for subsequent Deployah (and optionally kubectl) commands.
• Support switching namespace and/or kube context, in an oc project / kubens / kubectx familiar shape.
• Prefer a Deployah-native mode: switch by environment name (reads platform context, optional default namespace).
• Show current target clearly (deployah use / deployah project with no args).
• Tab completion for environments / contexts / namespaces where practical.
• Document how this interacts with flags (--context still wins) and with the local cluster kubeconfig (Deployah already prefers not to force-merge kind into ~/.kube/config).

Non-goals

• Replacing platform-file ownership of environment → cluster mapping.
• Implementing full oc login / OAuth flows.
• Multi-cluster project federation.
• Changing deploy semantics when -n / --context are explicitly set.

Proposed design

Command shape (names open)

Pick one primary name; others as aliases:

deployah use                 # show current
deployah use staging         # Deployah environment → context (+ ns if configured)
deployah use -n payments     # namespace only (oc project / kubens style)
deployah use --context kind-deployah
deployah project payments    # alias focused on namespace
deployah ctx                 # optional alias for context-only (kubectx-like)

Two complementary modes

Mode	Input	Effect
Environment (recommended default)	deployah use staging	Resolve environments.staging.context from platform file; set sticky defaults for Deployah; optionally update kubeconfig current-context
Namespace	deployah use -n foo / deployah project foo	Set namespace on current context (like oc project)
Context	deployah use --context X	Switch kubeconfig current-context (like kubectx)

Persistence

Recommendation: Deployah-only sticky state by default (Option B), with optional kubeconfig write for oc project parity.

Option	Mechanism	Notes
A – kubeconfig	ModifyConfig current-context / namespace	Closest to oc project; affects kubectl too
B – Deployah active state (default)	.deployah/active or ~/.config/deployah/active.yaml	Safer with localkube's separate kubeconfig path
C – shell export	eval $(deployah use staging --print-env)	Session-scoped; no file writes

Optional: --kubeconfig-write enables Option A when users want kubectl to follow. DPY_NAMESPACE already exists in session constants and should participate in precedence.

Show current

$ deployah use
environment: staging
context:     prod-eks
namespace:   payments
kubeconfig:  ~/.kube/config
source:      .deployah/active (flags override)

Precedence (document)

--context / --namespace flags
  -> DPY_* / process env
  -> deployah active state (this feature)
  -> platform environment.context
  -> kubeconfig current-context / namespace

Align with the existing README precedence table and extend it.

Failure modes

• Unknown environment name → list valid names (like resolve).
• Namespace does not exist → error unless --force (kubens -f style).
• Writing kubeconfig fails (permissions / missing file) → clear error.
• use with no platform file in env mode → fall back to context/namespace-only or error with hint.

Alternatives considered

1. Document kubectl config set-context --current --namespace= only. Works; ignores Deployah environments and localkube path quirks.
2. Only wrap kubectx/kubens. Extra deps; no environment awareness.
3. Environment switch that only prints flags (deployah use staging --print-flags). Useful for scripts; weak interactive UX alone.
4. Put namespace into deployah.yaml environments. Wrong layer for "where am I working right now"; sticky CLI state is enough.

Compatibility and migration

• Additive command; no change when unused.
• Explicit --context / -n remain authoritative.
• Related: deployah resolve --environments, deployah cluster kubeconfig, local cluster context kind-deployah.
• Skills (proposal: Agent Skills catalog and deployah skills install #28): teach deployah use for local vs remote workflows.

Test plan

• Unit: env name → resolved context written to active state
• Unit: precedence flags > active > platform > kubeconfig
• Manual: use local then deploy / status hit kind without --context
• Manual: use -n foo with and without --kubeconfig-write
• Docs: Commands table + precedence update; compare to oc project

Checklist

• I searched existing issues and discussions
• This includes enough design detail for implementation (not only a wish)