Plan: Phase 1 DCT Work — uis Shim + Namespace/Secret Flags

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

WORKFLOW.md - The implementation process

PLANS.md - Plan structure and best practices

Status: Active

Goal: Ship DCT's two Phase 1 items from INVESTIGATE-improve-template-docs-with-services.md: (1.8) the uis shim that lets users type bare uis ... commands inside DCT, and (1.9) updates to dev-template-configure to pass --namespace and --secret-name-prefix to UIS.

Priority: High — 1.8 unblocks TMP's README rewrites; 1.9 fixes the deploy-time crash-loop bug.

Last Updated: 2026-07-08

Note: Phases 1 and 2 code shipped in commits 41fa00a (feat: uis shim + dev-template-configure passes namespace + secret-name-prefix) and b33988a (feat: dev-template configure verbose output + v1.7.36), released in v1.7.36+. This doc was stale — it hadn't been updated since 2026-04-09 despite the work landing. Task 1.5 (four-input-mode test) and Phase 3 (end-to-end verification with TMP's rewritten templates) have no recorded confirmation, so their checkboxes remain unchecked below.

Investigation: helpers-no/dev-templates → INVESTIGATE-improve-template-docs-with-services.md (active)

Cross-team dependencies:

1.8: zero dependencies, can start immediately
1.9: depends on UIS 1.10 (uis configure --namespace/--secret-name-prefix flags + new JSON fields)

Overview

The Phase B integration work (completed 2026-04-06) confirmed the architecture works end-to-end, but real-user testing of python-basic-webserver-database surfaced UX problems:

C2: "uis: command not found" from inside DCT. Users see uis configure in docs and try to run it. The CLI lives inside the uis-provision-host container — not in DCT. The workaround is docker exec uis-provision-host uis ... everywhere, which makes READMEs unreadable.
Deploy-time crash-loop. The template's deployment.yaml references a Kubernetes Secret ({{REPO_NAME}}-db) that doesn't exist in the cluster. ArgoCD deploys the app, the pod tries to read the secret, fails, crash-loops.

This plan ships the DCT half of the fix.

Phase 1: The `uis` shim (1.8) — ✅ CODE DONE (1.5 unverified)

Tasks

1.1 Add uis_bridge_run_tty() function to .devcontainer/manage/lib/uis-bridge.sh:

uis_bridge_run_tty() {
    docker exec -it "$UIS_CONTAINER" uis "$@"
}

1.2 Created .devcontainer/manage/uis.sh with TTY/stdin/no-TTY routing + help fast path

#!/bin/bash
# /usr/local/bin/uis — DCT shim for the UIS CLI
set -e
source /opt/devcontainer-toolbox/manage/lib/uis-bridge.sh

# Fast path: help/no-args output is local-only — don't require UIS container
case "${1:-}" in
    ""|help|--help|-h)
        # Print DCT-flavoured usage that mentions the shim
        # Falls back to running 'uis help' if container is up; otherwise shows local message
        if uis_bridge_check 2>/dev/null; then
            uis_bridge_run_tty "$@"
        else
            cat <<'EOF'
uis — UIS CLI (proxied from DCT via docker-outside-of-docker)

Usage: uis <command> [args]

This is a DCT shim that forwards commands to the uis-provision-host
container. UIS provides commands for managing data services, deployments,
templates, and more.

Common commands (require uis-provision-host running):
  uis status               Show status of all UIS components
  uis deploy <service>     Deploy a service (postgresql, redis, ...)
  uis configure <service>  Configure a service for an app
  uis connect <service>    Connect to a service (psql, redis-cli, ...)
  uis template install <id>  Install a UIS stack template
  uis expose <service>     Expose a service via port-forward

⚠️  uis-provision-host container is not running.
    Start it from the urbalurba-infrastructure repo.
EOF
            exit 0
        fi
        ;;
    *)
        uis_bridge_check || exit 1
        if [ -t 0 ] && [ -t 1 ]; then
            uis_bridge_run_tty "$@"
        elif [ ! -t 0 ]; then
            uis_bridge_run_stdin "$@"
        else
            uis_bridge_run "$@"
        fi
        ;;
esac

1.3 Added uis symlink in image/Dockerfile (alongside config-host-info)
1.4 chmod +x already covered by existing chmod +x /opt/devcontainer-toolbox/manage/*.sh block
1.5 Test all four input modes (needs new image build):
- Interactive TTY: uis status (should show formatted output, no garbled escape codes)
- Piped stdin: echo "SELECT 1;" | uis configure postgresql --init-file - (should work, no TTY allocated)
- Non-TTY no stdin: uis status > out.txt (should redirect cleanly)
- Container down: docker stop uis-provision-host && uis status (should print clear error)
- Help fast path: docker stop uis-provision-host && uis help (should print local help, exit 0)

Validation

uis help works regardless of UIS state. uis status, uis connect, uis configure work when UIS is running. README rewrites can drop the docker exec uis-provision-host noise.

Phase 2: `dev-template-configure` passes namespace + secret name prefix (1.9) — ✅ DONE

UIS 1.10 shipped 2026-04-09 (PR #121, all 6 tester verification steps PASS). Confirmed present in code (dev-template-configure.sh lines ~361-382) as of 2026-07-08.

Tasks

2.1 Resolved namespace from ${PARAMS[subdomain]:-${PARAMS[app_name]:-$GIT_REPO}} — done in _configure_service
2.2 Resolved secret_name_prefix from $GIT_REPO (matches deployment.yaml {{REPO_NAME}}-db)
2.3 Pass both as new args via extra_args array — uis_bridge_configure already forwards them transparently
2.4 uis_bridge_configure already forwards arbitrary args via "$@" — no change needed
2.5 Updated JSON parsing in uis-bridge.sh: added UIS_SECRET_NAME, UIS_SECRET_NAMESPACE, UIS_SECRET_ENV_VAR globals, parsed in both ok and already_configured branches, reset on each call
2.6 Updated completion message: shows → .env: DATABASE_URL=... (local) and → K8s Secret: my-app-db in namespace my-app (cluster) when UIS returned secret fields. Falls back to writing .env.cluster for legacy callers (no GIT_REPO, older UIS).
2.7 Sourced git-identity.sh in dev-template-configure.sh and call detect_git_identity early to populate GIT_REPO

Validation

After running dev-template-configure on python-basic-webserver-database:

.env contains a working local URL
kubectl get secret <repo-name>-db -n <namespace> shows the secret exists
kubectl get namespace <namespace> shows the namespace exists
Re-running is idempotent (UIS returns already_configured)
The secret's DATABASE_URL key matches the manifest's secretKeyRef
A pod deployed via kubectl apply -f manifests/deployment.yaml would NOT crash-loop on missing secret

Phase 3: Test end-to-end with TMP's rewritten templates

Tasks (after TMP finishes 1.5/1.6 README rewrites)

3.1 In a fresh DCT devcontainer with UIS running, follow the new python-basic-webserver-database README literally:
- dev-template python-basic-webserver-database
- Edit template-info.yaml params
- dev-template-configure
- Run the Flask app, confirm /tasks returns seeded rows
3.2 Verify uis connect postgresql <db> from the new "Verify" section works
3.3 Verify uis status postgresql from the "Before you start" section works
3.4 Verify uis help works even when the UIS container is stopped
3.5 Test kubectl get secret <repo>-db -n <namespace> shows the secret with correct key

Validation

End-to-end happy path works with zero docker exec mentions in the README.

Acceptance Criteria

Items below marked (code confirmed 2026-07-08) were verified by reading the shipped source; they are not runtime-tested. Items with no annotation still need a live check.

Files to Create/Modify

New:

.devcontainer/manage/uis.sh — the shim

Modify:

.devcontainer/manage/lib/uis-bridge.sh — add uis_bridge_run_tty(), update uis_bridge_configure() to forward new flags, update JSON parsing
.devcontainer/manage/dev-template-configure.sh — resolve namespace + secret_name_prefix, pass to bridge, update completion message
image/Dockerfile — add uis symlink

No template changes needed — Option A (use existing {{REPO_NAME}} placeholder) means the deployment.yaml stays as-is.

Cross-team coordination

Item	DCT depends on	DCT blocks
1.8 (shim)	Nothing	TMP 1.5, 1.6, 1.7, 1.12 (README rewrites)
1.9 (--namespace)	UIS 1.10 (--namespace flag in `uis configure`)	Nothing — TMP READMEs reference the result, not the flag

Recommended sequence (from TMP 7MSG):

Day 1: DCT starts 1.8 (this plan Phase 1) in parallel with TMP and UIS
Day 2-3: DCT 1.8 lands → TMP can rewrite postgresql-demo README
Day 2-3: UIS 1.10 lands → DCT starts 1.9 (this plan Phase 2)
Day 3-5: DCT Phase 3 verification once TMP READMEs are ready

Status: Active​

Overview​

Phase 1: The uis shim (1.8) — ✅ CODE DONE (1.5 unverified)​

Tasks​

Validation​

Phase 2: dev-template-configure passes namespace + secret name prefix (1.9) — ✅ DONE​

Tasks​

Validation​

Phase 3: Test end-to-end with TMP's rewritten templates​

Tasks (after TMP finishes 1.5/1.6 README rewrites)​

Validation​

Acceptance Criteria​

Files to Create/Modify​

Cross-team coordination​

Status: Active

Overview

Phase 1: The `uis` shim (1.8) — ✅ CODE DONE (1.5 unverified)

Tasks

Validation

Phase 2: `dev-template-configure` passes namespace + secret name prefix (1.9) — ✅ DONE

Tasks

Validation

Phase 3: Test end-to-end with TMP's rewritten templates

Tasks (after TMP finishes 1.5/1.6 README rewrites)

Validation

Acceptance Criteria

Files to Create/Modify

Cross-team coordination