wxops darlane sync — Delete Propagation Fix​

The biggest change in this release: when you deleted a file locally during a darlane sync session, the file persisted in the pod indefinitely. The watcher only handled Write, Create, and Rename events — Remove was silently dropped.

Now: deletes are tracked in a separate map and flushed to the pod as a kubectl exec rm -rf call on the next debounce tick. Delete flushes always run before create/write flushes, so a file that's deleted and immediately recreated lands in the pod in the correct order.

✗  deleted 2 file(s): old_handler.go, old_util.go
↑  synced  1 file(s): handler.go

Initial Full Sync on Startup​

darlane sync now performs a full sync of all non-excluded files immediately after the watcher starts. This means the pod is always in a clean state from the moment the session begins — no more "why doesn't the pod have my latest code?" on a fresh debug session.

wxops darlane sync payment-api
# → initial sync: 14 file(s)
# watching  ./src  →  tenant-wxops/payment-api-darlane:/app

Suppress with --no-initial-sync if you want the old behaviour.

Max-Debounce Cap (2 s)​

The old debounce reset on every event. During a git checkout or a build emitting hundreds of files, the timer kept resetting and nothing flushed until the burst was completely done — sometimes 10–30 seconds of no syncs.

The debounce now has a 2-second hard cap: even if events are still arriving, the flush fires at the 2-second mark. Large file bursts get their first sync in ≤ 2 s, not after the burst finishes.

kubectl Retry​

Pods restart during development. Both sync and delete calls now retry up to 3 times with a 2-second delay between attempts:

⚠  pod not ready, retrying (1/3)…
⚠  pod not ready, retrying (2/3)…
↑  synced  3 file(s): main.go, handler.go, util.go

Graceful SIGINT / SIGTERM​

Ctrl-C now flushes any pending batch before exiting instead of dropping it:

^C
stopped.

CLI Download Proxy​

Developers previously needed direct Gitea access to download the wxops binary. v0.4.1 adds an authenticated download endpoint to the portal backend:

GET /api/v1/cli/download/:platform

The endpoint calls the Gitea releases API with the portal's service-account token and streams the latest binary back to your authenticated session. The CLI download card on the overview page now links directly to this endpoint — no Gitea credentials required.

Supported platforms: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64.

nginx Cookie Buffer Fix​

A 502 upstream sent too big header error on /auth/callback in Kubernetes deployments was traced to nginx's default 4 kB proxy buffer being too small for the AES-256-GCM Pinniped session cookie (id_token + access_token + refresh_token ≈ 3–4 kB). Fixed by adding proxy_buffer_size 32k to the /auth/ location block.

Also fixed: the Secure cookie flag is now set correctly from the X-Forwarded-Proto header rather than hardcoded, so production HTTPS deployments behind an Ingress controller work without config changes.

See the full Architecture docs or browse the Service Catalog guide to get started with v0.4.1.

What's New​

Darlane — Per-Environment Parallel Debug Pods (headline feature)​

A new class of developer capability: ephemeral debug pods that run in parallel with the real workload, scoped to a single environment, and fully governed by the same GitOps pipeline as every other config change.

What a Darlane pod gives you​

• Scale up on demand — replicas: 0 means zero cost at rest; scale to 1 when you need it and back to 0 when done
• Exec into your actual runtime — with the real env vars, secrets, and service mesh present (no local simulation)
• File-sync from local — stream changes from your workstation directly into the pod volume; the pod's hot-reload picks them up without a redeploy
• Mirror live traffic — via Mirrord; your local process receives real cluster traffic without re-routing production

Architecture: overlay-driven, not scaffold-time​

Darlane config lives in the overlay kustomization.yaml as a JSON 6902 op: add patch targeting spec.parameters.darlane on the XTenantApp resource:

# Minimal patch written by the portal to overlays/dev/kustomization.yaml
- op: add
  path: /spec/parameters/darlane
  value:
    enabled: true
    replicas: 0
    ttl: 4h

Dev overlays are committed directly to main. Staging and production overlays open a PR with the portal-managed label for platform-team review.

Promotion panel: Enable Darlane wizard​

The Darlane button appears on each environment row once the overlay exists.

Step 2 shows a diff-aware YAML preview labeled + added / ~ changed / − removed when reconfiguring an existing Darlane block.

Inline debug commands​

When Darlane is enabled, the portal shows copy-paste commands:

# Exec
kubectl -n <namespace> exec -it deployment/<app>-darlane -- bash

# Port-forward
kubectl -n <namespace> port-forward deployment/<app>-darlane 8080:8080

# Traffic mirror (Mirrord)
mirrord exec --target deployment/<app>-darlane --target-namespace <namespace> -- <cmd>

# File sync (wxops CLI)
wxops darlane sync <app>
wxops darlane sync <app> --local ./src --remote /app/src

Deployment naming follows the XTenantApp composition convention: dev → {appName}-darlane, staging → {appName}-staging-darlane, production → {appName}-production-darlane.

Permission model​

wxops CLI (headline feature)​

A standalone terminal client for the portal — the same REST API as the browser, without opening a browser.

Installation​

# Linux amd64
curl -L https://<portal-host>/api/v1/cli/download/linux/amd64 \
  -o /usr/local/bin/wxops && chmod +x /usr/local/bin/wxops

# macOS arm64
curl -L https://<portal-host>/api/v1/cli/download/darwin/arm64 \
  -o /usr/local/bin/wxops && chmod +x /usr/local/bin/wxops

# Or build locally from the repo root
make cli-install

Available targets: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64.

Commands​

wxops login — PKCE browser flow. Saves the session token to ~/.wxops/credentials.json. For CI, set WXOPS_PORTAL_URL + WXOPS_TOKEN env vars instead — WXOPS_TOKEN takes precedence over the credentials file.

wxops catalog list

wxops catalog list [--kind Component] [--lifecycle production]

Tabwriter output across all entity kinds. Filter by kind and/or lifecycle.

wxops catalog get <kind> <name>

Full details for a single entity — name, lifecycle, owner, type, description, source.

wxops debug <service> [--env dev|staging|production]

Resolves the entity, shows per-environment Darlane state, and prints ready-to-run kubectl, mirrord, and wxops darlane sync commands:

$ wxops debug payment-api

Darlane debug  payment-api
Namespace       tenant-wxops
Deployment      payment-api-darlane
Lifecycle       production

Darlane status
  dev          ✓  enabled
  staging      ·  overlay exists — Darlane not enabled
  production   —  no overlay

wxops darlane sync <app>

Watches a local directory with fsnotify, debounces rapid changes, and streams a tar archive into the Darlane pod using kubectl exec … tar xf -.

wxops version — prints wxops version v0.4.0.

CLI Download Card — Overview Dashboard​

The portal Overview page now includes a compact CLI download card in the right-hand sticky column (below the Identity panel). It lists download links for all platform targets and links to the CLI documentation.

Upgrade Notes​

No database migrations. No new required environment variables.

The wxops CLI binary is released alongside the portal image. Existing sessions are fully compatible — users who have already authenticated can re-login with v0.4.0 and the credentials file is reused.

Resources​

• Darlane reference
• CLI reference
• Architecture
• Deployment guide
• Environment variables

What's New​

Catalog Search & Filtering​

The catalog is now fully searchable and filterable without a page reload.

• Full-text search — ?search= matches name, title, description, and tags across all entities. Powered by in-process filtering on the backend's cached entity slice.
• Owner filter — ?owner=rocket-team returns entities owned by a team.
• Kind filter pills — All / System / Component / API / Resource / Group / Doc tabs.
• Lifecycle tabs client-side — the full entity dataset is fetched once, then lifecycle tabs filter in-browser. Tab counts are always accurate with no pagination mismatch.
• Cache invalidation webhook — POST /api/v1/webhooks/catalog/refresh (Bearer token) flushes the in-memory cache immediately. Wire to the gitops-infra Gitea push webhook to make new catalog commits visible instantly instead of waiting up to 5 minutes.

Global Command Palette (Ctrl+K / Cmd+K)​

Find any entity without leaving the keyboard.

• FlexSearch Document index built in-browser on first open (prefix tokenization for instant partial matches), 5-min TTL matching the backend cache
• Searches name, title, description, and tags across all entity kinds simultaneously
• Keyboard navigation: ↑↓ to move, Enter to navigate, Esc to dismiss
• Kind color badges and lifecycle hints on each result row

Session Notifications​

The bell icon in the top bar surfaces portal activity during your session.

• Fires on: project scaffolded, project imported, entity registered (PR opened)
• Background poll every 3 minutes detects catalog merges by comparing entity count to your session baseline → shows "Catalog updated: N new entries"
• Backed by sessionStorage — cleared automatically when the tab or session ends

Dracula-Inspired Dark Mode​

Dark theme overhauled to reduce eye strain during extended use.

• Background: #282a36-tone (L=0.20 — not near-black, has visible depth)
• Accent: lavender purple #bd93f9-tone for all interactive elements
• Muted text: Dracula comment color #6272a4 (blue-purple instead of flat gray)
• Foreground: warm off-white #f8f8f2

Environment Version Row​

Each Component detail page now shows the latest image tag deployed per environment.

• Three-column card: Dev (blue) / Staging (amber) / Production (green)
• Dev tags shown as dev-…-{sha7} (abbreviated); staging/production shown in full
• Relative timestamps: "today / yesterday / 5d ago / 2mo ago"
• Card hides when no tags exist — no empty-state noise
• New endpoint: GET /api/v1/catalog/entities/:kind/:name/versions

Lifecycle Promotion UI (headline feature)​

Full lifecycle promotion is now UI-driven, replacing the removed ArgoCD webhook.

New lifecycle model​

experimental ──► development ──► staging ──► production
     │                                            │
     └────────────── deprecated ─────────────────┘

• experimental = catalog entity only; no overlay, no deployment
• development = dev overlay on gitops-infra main; dev image tag present
• staging = staging overlay merged; v*-rc* image tag present
• production = production overlay merged; v* release tag present
• deprecated = locked; removal PR open for platform-team review

Scaffold breaking change​

The scaffold no longer generates overlays/dev/. The infra PR now contains base manifests only. Developers create the dev overlay through the Promotion panel when ready.

Promotion panel — two-step flow​

Step A — Create overlay PR:

1. Developer clicks "Create overlay" on the target environment row
2. Inline config form expands: replicas, ingress host, CPU/memory limits (all optional)
3. Portal opens a PR in gitops-infra titled [Promote] {team}/{app} → {env}
4. Platform-team reviews and merges

Step B — Confirm lifecycle:

1. Panel detects overlay on main and shows "Confirm"
2. One click updates the catalog lifecycle

If a promotion PR is already open, the row shows "PR #N pending" — preventing duplicates.

Permission matrix​

New endpoints​

Removed​

Team Ownership View​

The Group detail page now shows the full picture of what a team owns and depends on: APIs, Resources, and external APIs consumed by the team's components.

Doc Entity Improvements​

• Direct commit to main — Doc entities are committed directly to gitops-infra/catalog/; cache is invalidated immediately.
• Author-only draft visibility — spec.draft: true hides a Doc from everyone except the author and platform-team.
• docStatus editing — segmented control: proposed / under-review / accepted / deprecated / superseded.
• relatedTo editing — Doc entities can now link to Components, APIs, and Resources.

Breaking Changes​

1. Scaffold no longer generates overlays/dev/ — projects scaffolded after this release start at experimental. Use the Promotion panel to create the dev overlay.

   Existing projects: already have overlays/dev/ committed. Use the Promotion panel's Confirm button to reconcile the lifecycle.

2. POST /api/v1/webhooks/promote/:kind/:name removed — remove any ArgoCD notification or CI script calling this endpoint. Promotion is now portal UI-driven.

3. Lifecycle removed from edit panel — use the Promotion panel instead.

Upgrade Notes​

No database migrations. No new required environment variables.

Optional — cache invalidation webhook (recommended):

In Gitea → gitops-infra repo → Settings → Webhooks → Add:

• URL: https://<portal-host>/api/v1/webhooks/catalog/refresh
• Method: POST
• Authorization: Bearer <WEBHOOK_TOKEN>
• Trigger: Push events

Resources​

• Architecture
• Environment variables
• Deployment guide

What's New​

Golden-path scaffolding​

Project creation wizard

Four-step wizard — template selection → runtime config → platform features → review and create. Each step is independently navigable; the final step shows a per-step progress screen with timing as the portal commits files and creates resources.

Template system

Templates live in gitops-infra under a configurable directory. Each template carries a template.yaml that declares metadata, defaults, and recommends so the wizard can pre-populate fields and suggest optional features. Runtimes (language, version, package manager) are selectable per template.

Manifest generation

The portal generates and commits:

• tenants-apps/{team}/{app}/base/ — xtenant-app.yaml, xtenant-database.yaml (when database enabled), external-secret-*.yaml, catalog entity files
• tenants-apps/{team}/{app}/overlays/dev/ — kustomization.yaml, image-transformer.yaml, patch-xtenant-app.yaml
• tenants/{team}/{app}.yaml — ArgoCD Image Updater CR

ArgoCD Image Updater integration

image-transformer.yaml is required for Kustomize to reach spec/parameters/image on the XTenantApp CRD (Kustomize only natively substitutes images in standard Deployment/StatefulSet specs). The generated kustomization.yaml intentionally has no images: block — Image Updater adds it on first build. A static block would be overwritten on every reconcile, resetting the tag to latest.

The Image Updater CR is committed to tenants/{team}/{appName}.yaml (not inside tenants-apps/) with metadata.name: {appName} for a clean ArgoCD control-plane view.

Overlay patch correctness

patch-xtenant-app.yaml contains only env-specific overrides (replicas, resources, ingress, secretsFrom). appName, namespace, and image use omitempty so they are absent from the patch and inherit from base — previously empty string values were overriding the base and breaking the deployed config.

Git-flow branching and branch protection

Scaffolded repos have three branches: develop (default, direct push allowed), staging and main (PR required; main has a CI bot whitelist). CI bot identity (GITEA_BOT_USERNAME / GITEA_BOT_EMAIL) is injected into scaffolded CI files.

Vault and ExternalSecret

The portal writes a Vault KV secret at secret/{team}/{app} (create/update only — never reads or deletes) and generates ExternalSecret manifests that reference it. Existence of the Gitea repo and gitops config is checked before any Vault write.

Import existing repos

Register an existing Gitea project into the catalog without re-scaffolding. The import wizard lists all org repos, auto-fills the entity YAML, and commits catalog entity files to gitops-infra.

Config management via PR​

Edit-config wizard

Update XTenantApp platform features (replicas, resources, ingress, secrets, probes, rollout strategy) through a three-step diff-review UI:

1. Edit form with YAML preview
2. Review — structured summary of changes
3. Success — "what was updated" checklist and PR status

The form matches the scaffold wizard's visual language: rounded-xl border cards, lg:grid-cols-2 equal columns, pill step badges, nav buttons outside the grid.

templateId preserved on update

Updating a project's config previously cleared templateId from the XTenantApp manifest — the backend rebuilt the manifest from the request struct without that field. templateId is now echoed back from the frontend and threaded through the backend rebuild.

Gitops PR URL security

gitops-infra PR URLs are not included in any API response. Activity feed and success panels show titles and status only.

CI/CD and release visibility​

Each catalog Component entity (with a gitea/source-location annotation) now shows three live-data cards pulled from the Gitea API:

CI/CD status card

Latest Gitea Actions workflow runs with status badges (passed / failed / running), workflow name, branch, and relative time. Auto-refreshes every 30 seconds.

Releases card

Git releases and container images from the Gitea Package Registry. Shows version timeline, pre-release badge, release notes preview, image tags with pull command.

Packages card

Dependency tracking from the repo's manifest files: go.mod, package.json, requirements.txt, pyproject.toml. Shows direct vs. dev dependencies per ecosystem. Single fetch on mount (deps don't change often enough to poll).

Activity feed​

Two-tier loading: five most-recent portal-managed PRs load immediately; "Show all" expands to a full paginated view. Filtered by the portal-managed Gitea label so only portal-created PRs appear. Role-scoped: tenant teams see only their own team's activity.

Lifecycle webhook​

The lifecycle sync CI workflow lives in gitops-infra (not in the scaffolded project). It fires on push to main when tenants-apps/**/overlays/dev/kustomization.yaml changes — Image Updater's write-back after a successful build triggers the webhook, which promotes the entity lifecycle to development.

Team managers ({orgName}:{teamName}:Managers) can promote lifecycle stages alongside platform-team. PORTAL_EXTERNAL_URL has been removed; CI uses PORTAL_URL from Gitea repository secrets on gitops-infra.

Cluster views​

Namespace listing from Pinniped groups

GET /api/v1/clusters/:id/namespaces previously called the K8s namespaces endpoint, which returns everything (cluster-admin) or 403 (everyone else). Namespaces are now derived from the user's Pinniped group membership: Gitea OIDC groups arrive as orgName:teamName, mapping to tenant-{orgName}. Platform-team users fall through to the K8s API.

Identity card reload button

Reload re-fetches the Pinniped WhoAmI, refreshes namespace listing, and triggers a full refresh of pods and deployments — no browser reload required.

Upgrade Notes​

New environment variables​

PORTAL_EXTERNAL_URL removed​

Rename the secret used by the Gitea CI runner: PORTAL_EXTERNAL_URL → PORTAL_URL (Gitea repository secret on gitops-infra). The webhook token secret name is unchanged.

Namespace RBAC​

Ensure ClusterRoleBindings on spoke clusters use the full orgName:teamName string as the subject (not plain teamName). Tenant namespaces must be named tenant-{orgName}.

ArgoCD Image Updater​

Remove any static images: block from existing overlay kustomization.yaml files before enabling Image Updater — the two will fight over the tag value on every reconcile.

Resources​

• Architecture
• Golden-path git flow
• Environment variables

What's included​

Phase 1 — Identity & Multi-Cluster Access​

One login covers every spoke cluster. No per-cluster popups, no credential duplication.

• Pinniped Supervisor OIDC with PKCE — the portal federates to any upstream IdP (Dex, Gitea OAuth2, LDAP, SAML) via the Supervisor FederationDomain.
• RFC 8693 token exchange — the Supervisor id_token is exchanged for a short-lived audience-scoped token per spoke cluster.
• Pinniped Concierge mTLS certs — TokenCredentialRequest issues 15-minute client certificates; the portal caches them to avoid redundant requests.
• Cluster registry — clusters are registered via K8s Secrets in production (wxops.cloud/kind=cluster label) or a local clusters.json for development.
• Kubeconfig download — users can download a ready-to-use kubeconfig that calls the portal as a Pinniped exec-credential plugin.

Phase 2 — Service Catalog​

Browse every platform service, API, and infrastructure dependency from one place.

• Backstage-compatible entity parser — reads catalog-info.yaml files for kinds: Component, API, System, Group, and Resource.
• Gitea source — catalog entities are fetched from a read-only Gitea repository (gitops-infra/catalog/). A local filesystem reader is available for development and testing.
• 5-minute TTL cache — double-checked locking prevents thundering-herd refreshes under load.
• System relationship graph — each System entity renders a Mermaid diagram showing how its components, APIs, and resources connect.
• Entity detail page — links to runbooks, RFCs, and ADRs are grouped and surfaced directly on the entity page.

Container​

• Single Docker image — nginx, Go backend, and Next.js run together under supervisord. The Kubernetes Ingress is the only external entry point.
• Port layout — nginx on :80 (public); Go backend on :8080 (internal); Next.js on :3000 (internal).

What's next​

Resources​

• Architecture & auth flow
• Environment variables
• Cluster registry
• Service catalog