feat: uis-exec shim, port-forward verifier, quickstart parser, portsAttributes — v1.7.37

[terchris]

Summary

Five user-visible changes shipped together because they all surfaced during the v1.7.36 E2E test of python-basic-webserver-database against real UIS, and they're all about closing the "from clean clone to working app" gap.

1. uis-exec multi-call shim — kubectl/helm/k9s without installing anything in DCT

New manage/uis-exec.sh + Dockerfile symlinks for kubectl, helm, k9s. Same busybox-style multi-call pattern as the existing uis shim. From DCT, kubectl get pods Just Works (proxied through docker exec into uis-provision-host). Zero install in DCT, zero version drift between DCT's kubectl and the cluster's, no kubeconfig copying, no platform shenanigans. Add new shims by adding one symlink line.

2. Port-forward dual-check verifier in dev-template configure

The old code printed "Port forward (created by UIS)" based purely on UIS's JSON response without verifying. Two failure modes hit during E2E:

• (a) UIS auto-expose silently failed (kubectl port-forward process never created), but UIS still returned Status: ok
• (b) Docker Desktop vpnkit returned false-positive TCP handshakes even when the port-forward was dead — VS Code Code Helper accepted the TCP, but couldn't speak postgres protocol

New code does two checks:

• pgrep inside uis-provision-host (authoritative — process actually exists)
• TCP probe from DCT to host.docker.internal:port (what users care about)

Four-state output covers truly working / broken / vpnkit-false-positive / process-up-but-network-broken, with actionable recovery commands in each warning.

3. quickstart parser in dev-template

New parse_quickstart_block() reads an optional quickstart: block from template-info.yaml and prints it as the new "Run your app" step in the "Next steps" output. Schema:

quickstart:
  title: "Run the Flask app"
  commands:
    - uv venv
    - uv pip install -r requirements.txt
    - uv run python app/app.py
  note: |
    Free-form note about port, what to expect, etc.

Templates without quickstart get the existing "Start building your project" fallback — zero breakage. Tracks INVESTIGATE-template-quickstart-block.md (also in this PR).

4. portsAttributes 30000-39999 in user template

Excludes the entire UIS exposed-port range from VS Code auto-forward.

UIS uses a 3 + internal port convention for every service:

Service	Internal	UIS exposed
postgresql	5432	35432
mysql	3306	33306
redis	6379	36379
elasticsearch	9200	39200
qdrant	6333	36333
mongodb	(27017)	37017
authentik	(9000)	39000

So one rule covers every current and future UIS service. Fixes the bug where VS Code Code Helper intercepted port 35432, accepted the TCP handshake, but couldn't speak postgres protocol — causing psycopg2 to hang forever.

5. Three INVESTIGATE files updated/added

• INVESTIGATE-host-identity-and-template-defaults.md — adds "Bug C surfaces in TWO places" rewrite (welcome message + dev-check both warn) plus a real-world reproduction section captured during the v1.7.36 E2E run (vscode@localhost shown)
• INVESTIGATE-kubeconfig-in-devcontainer.md — new Option F section: the uis-exec passthrough approach this PR ships, with pros/cons vs the existing host-kubeconfig-copy options (A-E)
• INVESTIGATE-template-quickstart-block.md (new) — captures the design + Q1-Q6 decisions for the quickstart schema

Test plan

End-to-end validated in delete-test against real UIS (v1.7.36 + hot-patches):

• dev-template-configure verbose output renders correctly
• Port-forward verifier shows "verified reachable from DCT" when kubectl port-forward exists
• Port-forward verifier shows "NOT reachable" when probing a known-closed port
• kubectl get secret delete-test-db -n delete-test works via the new shim
• Decoded secret returns the cluster-internal URL (postgresql.default.svc.cluster.local:5432)
• Flask app at /tasks returns 3 seeded rows end-to-end via host.docker.internal:35432 → kubectl port-forward → postgres pod
• portsAttributes rule prevents VS Code from intercepting 35432 (no manual Ports tab cleanup needed)
• CI Tests pass
• Build and Push Container Image succeeds, image published as :1.7.37 and :latest
• Deploy Documentation passes

🤖 Generated with Claude Code