# Plan: Devcontainer Unit Test Workflow Stability & Build Reuse

Date: 2026-03-04
Status: IMPLEMENTED

---

## Overview

This document captures the dev-path work completed to make unit tests reliable
inside containerized development and to reduce unnecessary rebuilds.

The original issue observed during `just test-unit` was a permission mismatch on
the workspace `target/` directory when running in container contexts. That made
unit tests fail before execution and also risked repeated full recompiles.

---

## Goals

1. Ensure `just test-unit` works in devcontainer-style execution.
2. Avoid forced full rebuilds when source/tests change.
3. Keep scope focused on development workflow (not production packaging).

---

## Root Cause

- `just test-unit` delegates to `scripts/run_unit_tests.sh`.
- The script previously assumed `target/` was writable.
- In container runs, workspace bind mounts can present UID/GID ownership that
  makes `target/` unwritable to the container user.
- This caused failures during stub compilation and cargo lock writes.

---

## Implemented Changes

### 1) Unit-test target directory fallback logic

Updated `scripts/run_unit_tests.sh` to select a writable target directory in a
stable order:

1. `<project>/target` (preferred)
2. `<project>/.cargo-target` (project-local fallback)
3. `$HOME/.cache/pg_trickle-target` (persistent user cache)
4. `${TMPDIR:-/tmp}/pg_trickle-target` (last resort)

Other script updates:

- Stub library path now uses `CARGO_TARGET_DIR`.
- Test binary discovery now resolves from `CARGO_TARGET_DIR`.
- Fallback directory creation is non-fatal when unwritable.

### 2) Devcontainer cache mount enhancement

Updated `.devcontainer/devcontainer.json` mounts to add persistent Cargo git
cache reuse:

- Added mount for `/home/vscode/.cargo/git`.

This complements existing registry/target/pgrx mounts and reduces dependency
re-download/re-resolution overhead when rebuilding/reopening devcontainers.

---

## Validation Performed

- Ran `just test-unit` inside containerized execution path.
- Confirmed successful unit-test completion (`1007 passed`).
- Confirmed permission-path failures were eliminated by target fallback logic.

---

## Scope Decisions

- We intentionally kept final scope on dev workflow improvements.
- E2E/CNPG Dockerfile optimization experiments were not retained as the primary
  deliverable for this task.

---

## Follow-ups (Optional)

1. Add a short note in `CONTRIBUTING.md` about container UID/GID effects on
   bind-mounted `target/` and how fallback target selection works.
2. Add a lightweight CI/unit check that executes `scripts/run_unit_tests.sh` in
   a containerized environment with non-root user to guard against regressions.