Claude Code transcript

This is a solid idea, and the good news is the codebase is already about 70% of the way there structurally. Here's my assessment after reviewing docs/webapp.md and the build machinery.

What exists today, and why it helps

The webapp path is already a "wrapping scheme" in all but name — it's just hardcoded and lives off to the side:

• Base image recipes live in-tree at src/stack/data/container-build/bozemanpass-webapp-base/ and bozemanpass-nextjs-base/. Each has a base Containerfile plus a Containerfile.webapp that does the two-stage "copy app repo in, build, produce runtime image" dance.
• The seam you need already exists: build_webapp.py drives the generic process_container() by overriding three env vars — STACK_CONTAINER_BUILD_CONTAINERFILE, STACK_CONTAINER_BUILD_WORK_DIR (the app repo), and STACK_CONTAINER_BUILD_TAG. That env contract is the wrapper interface; it just isn't formalized.
• External container builds are already supported: process_container() looks for stack-files/containers/<name>/build.sh in fetched repos, and repos are fetched/discovered by convention under STACK_REPO_BASE_DIR. So the "definitions live in their own repos" part has an existing pattern to copy.

What's missing is exactly what you identified: webapp-ness is not a first-class concept in stack.yml (it's a separate webapp build command family with a special-cased webapp-template stack and some post-hoc YAML rewriting in deploy_webapp.py), and there's no way to enumerate or add wrapping schemes.

Proposed shape

1. Make the wrapper an explicit attribute on a container entry in stack.yml. Something like:

containers:
  - name: myorg/my-site
    ref: github.com/myorg/my-site
    wrapper: static-content        # resolved by name among fetched wrapper repos
    # or fully qualified: wrapper: github.com/bozemanpass/static-content-wrapper

This slots cleanly into the decision tree in process_container() as a fourth branch alongside "explicit build script / inferred build.sh / repo Dockerfile fallback": if wrapper is present, resolve the wrapper, then reuse the existing env-var override mechanism to build the app image from the wrapper's Containerfile with the app repo as build context. No new build engine needed.

2. Define a wrapper repo as a small, declarative artifact. A git repo (or directory in one) containing a manifest — say wrapper.yml — plus the build materials:

name: static-content
description: Serve static HTML with nginx
base-container: bozemanpass/static-base   # built/pulled like any other container
containerfile: Containerfile.app          # the wrapping build, context = app repo
port: 80
# optional: runtime-env hook, healthcheck path, detect script

Discovery then mirrors stack discovery exactly: stack fetch repo pulls it into the dev root, and enumeration is an rglob for wrapper.yml (same as locate_stacks_beneath() rglobs stack.yml). Add a stack list wrappers to surface them. clone_all_repos_for_stack() needs to learn to also fetch wrapper refs, same as it fetches container refs today.

3. The contract a wrapper must satisfy is worth writing down explicitly, because it's what keeps this generic rather than a pile of special cases:

• A base image, built once and content-hash tagged like any other container (so it participates in the existing pull-or-build / ghcr publishing path — important so users don't have to build base images locally, and so air-gapped/offline use degrades gracefully).
• An app-image build parameterized only by the app repo as build context.
• A runtime convention: what port it serves on, and how runtime config is injected. This last one is where schemes genuinely differ — nextjs needs the apply-runtime-env.sh env-substitution trick; static content needs nothing. Making it a declared property of the wrapper rather than baked into deploy code is the key abstraction win.

4. Migrate, don't fork. The existing webapp-base and nextjs-base should become the first wrapper repos (alongside the new static one, which is trivial: nginx base + COPY . /usr/share/nginx/html). stack webapp build can survive as sugar — auto-detect the wrapper (package.json sniffing already exists in determine_base_container()) and delegate to the generic path. Buildpack-style auto-detection is nice for the convenience CLI, but I'd keep stack.yml explicit, as you suggested — declarative manifests shouldn't guess.

Things to watch

• Prior art: this is conceptually Cloud Native Buildpacks / Nixpacks territory. I'd deliberately not adopt CNB — it's heavyweight and would replace your build pipeline rather than plug into it — but it's worth borrowing its vocabulary (detect/build phases, builder contract) and being able to answer "why not buildpacks" (answer: you already have a hash-locked container build system; you just need a thin parameterized-Containerfile convention on top of it).
• Reproducibility: wrapper repos should participate in the existing lock-file scheme (like container.lock), so a deployment pins both the app repo ref and the wrapper ref. Otherwise a wrapper repo update silently changes what everyone's images look like.
• Cleanup opportunity: the webapp-template special case in stack_is_external() and the _fixup_container_tag/_fixup_url_spec YAML-rewriting in deploy_webapp.py are symptoms of webapp-ness not being in the model. Once a wrapped container is a normal stack component, those should be deletable — a wrapped component with a declared port composes with the existing http-proxy spec machinery like anything else.
• Bootstrap ordering: building a stack now has a cross-repo dependency (app repo + wrapper repo + possibly a prebuilt base image). The fetch/prepare flow needs to resolve wrappers before the container build starts, and error messages for "wrapper not fetched" should be good, since this will be a common first-run stumble.

Overall: I'd frame it as "formalize the env-var seam that build_webapp.py already uses into a named, discoverable wrapper contract, hosted in repos and resolved like external containers." The static-content case then becomes a ~20-line wrapper repo and a good proof that the abstraction is real. Happy to sketch the wrapper.yml schema and the process_container() changes in more detail if you want to take it further.

The webapp test turns out to be a nearly ideal regression harness for this: it builds the real test-progressive-web-app from scratch with webapp build, runs the image, and — the important part — does a before/after check that a runtime env var (CERC_WEBAPP_DEBUG) shows up in served pages only when set at docker run time. That's a direct test of the runtime-env-injection contract, which is exactly the piece most likely to break when the wrapping machinery moves. It also smoke-tests webapp deploy. So "existing tests still pass" is a genuinely meaningful invariant here, not just a syntax check.

On the prior art, for your reading list: Heroku buildpacks are the original (detect/compile/release contract), Cloud Native Buildpacks (buildpacks.io) is the CNCF standardization of that idea with its own image-building machinery (pack, lifecycle phases), and Nixpacks / Railpack (Railway) are the modern lightweight takes — they auto-detect the app type and generate a build plan rather than running opaque builder images. Vercel/Netlify do the same thing internally but don't expose it as a pluggable artifact. The useful borrowable ideas are the explicit detect-vs-build phase split and the notion that a builder is a versioned, published artifact — not their tooling.

For the unbundling itself, I'd phase it so the test gates each step independently:

Phase 1 — abstraction in-tree, nothing moves. Introduce the wrapper.yml manifest and resolution code, and convert bozemanpass-webapp-base/ and nextjs-base/ into in-tree wrappers (manifest + their existing Containerfiles, essentially unchanged). Rewire webapp build to go through the generic wrapper path instead of its hardcoded determine_base_container() → env-var plumbing. The webapp test must pass with zero changes to the test script. This is the pure refactor step, and doing it in-tree first means the test failure surface is only the abstraction, not repo fetching.

Phase 2 — externalize. Move the two wrappers to their own repo(s) (e.g. bozemanpass/webapp-wrappers or one repo per wrapper, matching how you split docker-ingress-stack), teach resolution to find fetched wrappers under STACK_REPO_BASE_DIR, and have the test fetch the wrapper repo the same way it already clones test-progressive-web-app. One decision to make here: whether the two existing wrappers stay bundled as builtins (resolution order: fetched repos override in-tree) or go fully external. Fully external is cleaner and matches your stated goal; the cost is that webapp build on a fresh machine needs network to fetch the wrapper — mitigated if the base images are published to ghcr so only the small wrapper repo needs cloning.

Phase 3 — the payoff. Add the static-content wrapper as a new external repo (nginx + COPY), add the wrapper: field to stack.yml container entries wired into process_container(), and a small test that deploys a static-HTML repo through a stack. This is also when the webapp-template special case and the _fixup_* rewrites in deploy_webapp.py become deletable.

One thing Phase 1 will surface immediately: the runtime-env scripts (apply-runtime-env.sh etc.) currently live in the base image's scripts/ directory and are shared between the two bases. They'll need to belong to the wrapper (baked into its base image), which is the right home anyway — a static wrapper simply won't have them.

If you want to proceed, I'd start on Phase 1 — it's self-contained in this repo and the webapp test tells us when it's done. Want me to draft the wrapper.yml schema and the resolution module as a first PR-sized chunk?

Phase 1 code is in place and the full webapp test is now running in the background (currently pulling the node base image — it'll take a few minutes to build the PWA). I'll report the result when it finishes.

What's changed so far:

• src/stack/build/wrappers.py (new) — the Wrapper class, wrapper.yml manifest loading, discovery (get_available_wrappers(), currently scanning the built-in data/container-build/*/wrapper.yml), name/base-container resolution, and detection (detect: rules with a package-json-dependency rule, falling back to the wrapper marked default: true).
• wrapper.yml manifests for the two existing schemes: webapp (webapp-base, the default) and nextjs (nextjs-base, detected via a next dependency in package.json).
• build_webapp.py now resolves a wrapper (new --wrapper option; --base-container kept working for compatibility) and takes the app-build Containerfile path from the manifest instead of the hardcoded name convention.
• determine_base_container() in deploy/webapp/util.py now delegates to wrapper detection, preserving its signature for the registry-deploy path.
• docs/webapp.md gained a short "Wrappers" section documenting the manifest and --wrapper.

Lint is clean repo-wide, and unit-level checks confirm resolution/detection behaves identically to the old hardcoded logic (default → webapp-base, next dependency → nextjs-base, webapp/next app type → nextjs-base).

The test is deep into the meaningful part — it auto-detected the nextjs wrapper and is running the Next.js production build inside the wrapper's Containerfile, so the new resolution path is working end-to-end. Still a few minutes from the final before/after env-injection checks; I'll confirm the result when it lands.

On the repos: you can create them whenever convenient — they're needed at the start of Phase 2, and empty is fine since I'll prepare the content as part of that phase. My suggestion on naming/split:

• One repo per wrapper, named after the base image: bozemanpass/webapp-base and bozemanpass/nextjs-base. The repo-name-equals-image-name convention pays off directly: image_registry_for_repo() already maps github.com repos to ghcr.io, so the existing pull-or-build machinery would find prebuilt base images at ghcr.io/bozemanpass/webapp-base with no extra plumbing. The two bases don't actually share files today (each has its own copy of scripts/), so there's no shared-code argument for a combined repo, and per-repo locking means each wrapper versions independently.
• Each repo gets: wrapper.yml, Containerfile (base image), Containerfile.webapp (app build), build.sh, scripts/.
• Later, Phase 3 adds a third: something like bozemanpass/static-content.

If you'd rather not squat those image-style names as repo names, a single bozemanpass/container-wrappers repo with one subdirectory per wrapper also works (the path: field in container refs already supports subdirectory layouts) — but the per-repo version is my recommendation.

One thing to decide before Phase 2 work starts: whether you want a PR for Phase 1 first so the external-discovery change builds on a merged baseline. I'd suggest yes — once this test passes I can branch, commit, and open it.

The full webapp test suite passed with the Phase 1 changes — exit code 0, all checks green:

• webapp build auto-detected the nextjs wrapper and built bozemanpass/test-progressive-web-app:stack through the new wrapper path.
• BEFORE: PASSED / AFTER: PASSED — the runtime env-injection contract (the part most at risk in this refactor) behaves identically: the test string appears in served pages only when set at docker run time.
• The webapp deploy deployment-create test also passed.

So Phase 1 is complete and validated: the wrapper abstraction is in, the two existing schemes are expressed as wrapper.yml manifests, and behavior is unchanged. The working tree has the changes uncommitted (3 modified files, 3 new). Say the word and I'll branch, commit, and open the Phase 1 PR — and as covered earlier, you can create the two external repos (bozemanpass/webapp-base, bozemanpass/nextjs-base) whenever you like; Phase 2 starts by populating them.

Good naming — the stack-wrapper- prefix makes them self-describing and greppable in the org, and it costs nothing technically: the base image name (bozemanpass/webapp-base etc.) is declared inside wrapper.yml, not derived from the repo name, and ghcr.io package names don't need to match repo names either, so the prebuilt-base-image pull path is unaffected.

One detail to settle: the nextjs wrapper. Your two names suggest either a bozemanpass/stack-wrapper-nextjs as a third repo, or folding nextjs into stack-wrapper-webapp as a subdirectory (the two are close cousins — both node bases, and wrapper.yml discovery by rglob handles multiple wrappers per repo fine). I'd lean to the separate stack-wrapper-nextjs repo purely so each wrapper versions and locks independently — but if you'd rather remember one repo for "the node webapp wrappers," a combined stack-wrapper-webapp containing both manifests works just as well with the discovery mechanism as designed. Your call when you create them; Phase 2 code is identical either way.

Meanwhile, shall I go ahead and branch/commit/open the Phase 1 PR? Everything is validated and sitting uncommitted in the working tree.

Phase 2 implementation is done and locally validated; the full webapp regression test is running in the background now. Status so far:

Stack tool changes (on top of Phase 1, all uncommitted in this repo): - get_available_wrappers() now also discovers wrapper.yml manifests in repos fetched beneath the repo base dir (STACK_REPO_BASE_DIR), with external wrappers shadowing built-ins of the same name. - process_container() honors an absolute build-script path on a ContainerSpec, and webapp build passes the wrapper's own build.sh — so base containers build correctly from external wrapper directories that don't follow the in-tree naming convention. - New stack webapp wrappers command lists discovered wrappers with their source (builtin vs. path). - docs/webapp.md updated for external wrapper repos and the listing command.

Wrapper repo clones populated (files written, not committed — I'll leave commits to you or do them on request): - ~/projects/bpi/stack-wrapper-webapp: webapp-base/ and nextjs-base/ (copied verbatim from in-tree), plus a README. - ~/projects/bpi/stack-wrapper-static-content: the new wrapper — wrapper.yml, nginx-based Containerfile, two-stage Containerfile.app (strips .git from the served content), build.sh, README.

Validated locally: - stack webapp wrappers with a dev root containing the two repos lists all three wrappers, external paths shadowing builtins. - End-to-end static content: built bozemanpass/my-static-site:stack from a bare index.html directory via --wrapper static-content, ran it, and nginx served the marker page correctly.

I'll report when the regression test finishes. Note the in-tree wrapper copies are deliberately still present — removing them (and deciding whether webapp build should auto-fetch stack-wrapper-webapp when no wrapper is found) is the step that can only land after you push the wrapper repos to GitHub.

The Phase 2 regression run is green — the full webapp test suite passed again with all the changes in place (BEFORE/AFTER env-injection checks and the deploy-create test all PASSED, exit code 0).

So the current state is:

• stack repo (uncommitted): Phase 1 (wrapper abstraction, manifests, rewired webapp build) plus Phase 2 (external discovery under STACK_REPO_BASE_DIR with external-shadows-builtin precedence, absolute build-script support for external wrapper dirs, stack webapp wrappers listing, docs). Lint clean, full webapp test passing.
• stack-wrapper-webapp clone: populated with webapp-base/ and nextjs-base/ plus README (uncommitted).
• stack-wrapper-static-content clone: populated with the new nginx wrapper plus README (uncommitted); proven end to end locally — a bare index.html directory built and served via --wrapper static-content.

Since you're handling branches/PRs: the stack repo changes and the two wrapper repos are independent and can be pushed in any order.

Remaining follow-ups once the wrapper repos are on GitHub:

1. Remove the in-tree wrapper copies from src/stack/data/container-build/ so the external repos are authoritative. This is the step that needs a decision: either webapp build auto-fetches bozemanpass/stack-wrapper-webapp when no suitable wrapper is found (keeps the zero-config UX and the CI test unchanged), or it errors with a "run stack fetch repo bozemanpass/stack-wrapper-webapp" message (more explicit, needs a one-line test change). I'd lean auto-fetch with a log line saying what it fetched.
2. Phase 3: the wrapper: field on stack.yml container entries wired into process_container(), a static-site deployment test, and then deleting the webapp-template special case and the _fixup_* rewrites in deploy_webapp.py.

Just tell me when the repos are pushed (and which flavor of step 1 you want) and I'll continue.

The cutover is implemented and the decisive test is now running in the background: a rebuilt shiv package (the old one still embedded the in-tree wrappers), deleted base/app images, and the unchanged CI webapp test script — which now must auto-fetch the wrapper repos from GitHub and build everything from external wrapper definitions. I'll report when it completes.

What changed in this step:

• Deleted src/stack/data/container-build/bozemanpass-webapp-base/ and bozemanpass-nextjs-base/ — only the shared build-base.sh and default-build.sh remain in-tree. The external repos are now authoritative.
• Auto-fetch: wrappers.py gained DEFAULT_WRAPPER_REPOS (stack-wrapper-webapp, stack-wrapper-static-content) and fetch_default_wrapper_repos(). Both webapp build and the legacy determine_base_container() path retry after fetching when no wrapper matches, so zero-config UX is preserved (verified: with a completely empty repo base dir, webapp build --wrapper static-content cloned both repos from GitHub, built, and the container serves the content).
• Docs updated to describe repos-as-source-of-truth and auto-fetch.

One git housekeeping note: I noticed you had staged the Phase 1 changes in the index. I've left your staging mostly intact, with one exception — the two in-tree wrapper.yml files got unstaged (and are now deleted from the working tree along with their directories, as unstaged deletions). Depending on how you want to slice the PRs, you may prefer to just re-stage everything as one combined commit — the working tree is the correct final state either way.

Phase 2 is complete and fully validated. The unchanged CI test script, run cold (fresh repo base dir, rebuilt package with no in-tree wrappers, deleted images), auto-fetched both wrapper repos from GitHub, auto-detected the nextjs wrapper from the external repo, built the PWA through it, and passed every check — BEFORE/AFTER env injection and the deploy-create test, exit code 0.

Final state:

• stack repo (working tree, ready for you to commit/PR): wrapper abstraction with wrapper.yml manifests; discovery of wrappers in fetched repos; auto-fetch of the two default wrapper repos when nothing matches (zero-config UX preserved, CI needed no changes); stack webapp wrappers listing command; in-tree wrapper directories deleted; docs updated. Lint clean.
• stack-wrapper-webapp / stack-wrapper-static-content on GitHub: authoritative wrapper definitions, proven working via real clones.

That completes what we scoped as Phases 1 and 2, plus the static-content wrapper itself from Phase 3. What remains of Phase 3, whenever you want it:

1. The wrapper: field on stack.yml container entries, wired into process_container() — so a static-HTML repo can be deployed just by listing it in a stack.
2. A deployment-level test for that path (static site through a full stack deploy).
3. Cleanup of the webapp-template special case in stack_is_external() and the _fixup_* YAML rewrites in deploy_webapp.py, which become unnecessary once wrapped containers are ordinary stack components.
4. Optionally later: publishing the base images to ghcr so fresh machines pull rather than build them, and lock-file participation for wrapper repos.

The static content test passes end to end — all four checks green (INDEX, SUBDIR, CSS, and GIT-NOT-SERVED), run against the built shiv package with a fresh repo base dir, so it also exercised the real auto-fetch of the wrapper repos from GitHub.

What was added:

• ~/projects/bpi/stack-test-static-content (fixture, uncommitted for you to push): index.html with a marker string, pages/about.html with a second marker, and css/style.css — enough to prove recursive content copying, subdirectory serving, and asset types beyond HTML.
• tests/static-content-test/run-static-content-test.sh: mirrors the webapp test structure — clones the fixture from GitHub, builds via webapp build --wrapper static-content, runs the container, and verifies the index page, a subdirectory page, the CSS file, and that /.git/config is not served (validating the .git strip in Containerfile.app). It supports a STACK_TEST_STATIC_CONTENT_REPO override for local runs against an unpushed fixture (which is how I validated it, via a throwaway scratch clone of your fixture content).
• .github/workflows/test-static-content.yml: same shape as the webapp workflow (checkout, uv, shiv build, run test).

Once you commit and push the fixture repo content, the test will work as-is in CI — the script's default clone URL points at github.com/bozemanpass/stack-test-static-content. Everything in the stack repo (test script + workflow) is in the working tree uncommitted, alongside the Phase 2 changes.

Everything is green and ready to go:

• The static content test passed against the real pushed GitHub fixture, exactly as CI will run it — clone from github.com/bozemanpass/stack-test-static-content, auto-fetch of the wrapper repos, build via the static-content wrapper, and all four serving checks passed.
• Your staged set is complete: the wrapper abstraction (wrappers.py), the rewired build/deploy code, the in-tree wrapper deletions, docs, the new test script, and the CI workflow are all in the index with nothing left unstaged.

So the whole arc is done and validated: wrappers are a first-class, discoverable abstraction; the two webapp schemes live in stack-wrapper-webapp as the source of truth; static content hosting works via stack-wrapper-static-content with its own regression test; and the existing webapp test passes unchanged throughout. Once you commit and push, both the webapp and static-content workflows should pass in CI on the first run.

Whenever you want to pick up Phase 3 (the wrapper: field in stack.yml so wrapped repos deploy as ordinary stack components, plus retiring the webapp-template special case and the _fixup_* rewrites), just say so.

Sounds good. If useful, here's a summary you can paste into the PR description:

Generalize webapp container wrapping into discoverable "wrapper" schemes

Introduces a wrapper abstraction: a wrapper.yml manifest pairing a base container image with a containerfile that builds app source into a servable image (base image, app containerfile, serving port, optional auto-detection rules).

• Wrapper definitions now live in their own repositories (stack-wrapper-webapp, stack-wrapper-static-content); the in-tree webapp-base/nextjs-base build files are removed.
• Wrappers are discovered from any repo fetched beneath STACK_REPO_BASE_DIR; stack webapp build auto-fetches the default wrapper repos when none match, so the zero-config UX is unchanged.
• New stack webapp wrappers command lists available schemes.
• webapp build gains --wrapper; --base-container still works.
• New static content hosting support (nginx wrapper) with a new test suite (tests/static-content-test/) and CI workflow, using the stack-test-static-content fixture repo.
• Existing webapp test suite passes unchanged.

Two small things worth knowing before you push: the Webapp Test and the new Static Content Test workflows both now depend on network access to the two wrapper repos (that's by design — CI validates the real auto-fetch path), and the first CI run will be the first cold build of the base images from the external repos. Both scenarios passed locally, so I expect green, but if anything surprises us in CI I'm happy to dig in.

Sounds like a plan. I've noted the current state in my project memory so the next session picks up cleanly: the wrapper abstraction and static content support are merged via your PR, the external repos (stack-wrapper-webapp, stack-wrapper-static-content, stack-test-static-content) are the source of truth, and the agreed Phase 3 backlog is:

1. wrapper: field on stack.yml container entries wired into process_container() — deploy a wrapped repo as an ordinary stack component.
2. A deployment-level static-site test through full stack deploy.
3. Retiring the webapp-template special case in stack_is_external() and the _fixup_* rewrites in deploy_webapp.py.
4. Eventually: publishing base images to ghcr and lock-file participation for wrapper repos.

Whenever you've got the fresh branch ready, just say go and we'll start on the stack.yml integration.

Phase 3 implementation is in place; the full test (build phase + new deployment phase) is running in the background against a freshly built package. What's implemented:

• wrapper: field on stack.yml container entries — parsed into StackContainer/ContainerSpec (also honored in container.yml, so a repo can declare its own wrapping). process_container() routes wrapped containers to a new _process_wrapped_container(): resolve the wrapper (auto-fetching the default wrapper repos if needed), build its base container, then wrap the app source repo using the wrapper's build script + containerfile. The existing repo-hash/tag/lock machinery in build_containers() is untouched and applies to wrapped containers as-is — so a wrapped container gets content-hash tagging for free.
• I also fixed a latent ordering issue while wiring this: the absolute-build-script branch now runs before the external-stack branch in process_container(), which would otherwise crash on file_path=None when a wrapped build happens inside an external stack (exactly the new test's scenario).
• stack-test-stacks clone: new test-static-content stack — a container entry pointing at the pure-HTML stack-test-static-content repo with wrapper: static-content, plus its compose file. This is the original vision end to end: a repo containing only HTML, deployed by listing it in a stack.
• Test extended: run-static-content-test.sh now has a deployment phase — fetch/prepare/init/deploy/manage start against the test-static-content stack, verifies the served markers on the mapped port, and tears down with --delete-volumes on exit. It supports a STACK_TEST_STACKS_REPO override for local runs (used now, since your stack-test-stacks additions aren't pushed yet).
• Docs: wrapper: documented in docs/stack-files.md's stack.yml reference.

Lint is clean. I'll report the test outcome when it lands.

The wrapper: field is confirmed working through prepare — the wrapped build ran inside the normal container pipeline. Both regression suites (webapp + docker deploy) are now running sequentially in the background, since the process_container() reordering touches code paths they exercise. I'll summarize once they're done.

Thanks — that unblocks the final validation: once the regression suites finish, I'll rerun the static content test without the local override, so it exercises the exact CI path (stack fetch repo bozemanpass/stack-test-stacks from GitHub). The webapp and deploy regression runs are still going; I'll report all three results together.

Indeed! Waiting on the regression runs — the Next.js build in the webapp test plus the full todo-stack deploy test take a few minutes combined. As soon as they land I'll do the final no-override run of the static content test against the pushed stack-test-stacks, then give you the full Phase 3 wrap-up so you can PR it.

And here's a PR description if you want it:

Add wrapper: support to stack.yml container entries

A container entry can now specify a wrapper scheme, so a repository containing no container build files (e.g. pure static HTML) can be deployed just by listing it in a stack:

containers:
  - name: bozemanpass/my-static-site
    ref: myorg/my-static-site
    wrapper: static-content

• Wrapped containers build through the normal container pipeline (_process_wrapped_container in build_containers.py): the wrapper's base image is built first, then the app source repo is wrapped using the wrapper's containerfile. Content-repo hash tagging and repo fetching apply as for any container; wrapper repos are auto-fetched if not present.
• wrapper may also be declared in a repo's own container.yml.
• Fixes a latent UnboundLocalError in get_repo_ref() (both Stack and ContainerSpec) for remote URLs that are neither https:// nor git@ form.
• Extends the static content test with a full deployment phase (prepare/init/deploy/start of the new test-static-content stack from stack-test-stacks, marker verification, teardown).
• Documents the field in docs/stack-files.md.

All of: static content test (build + deploy phases, CI configuration), webapp test, and docker deploy test pass locally.

That wraps this phase — over to you for the PR.

Yes, there was a real gap, and I've filled it — the changes are in the working tree ready to add to the baking PR (they're docs-only, so pushing them onto the same branch is low-risk):

The gap: wrapper authorship was undocumented — the wrapper.yml schema, the build.sh env-var contract, the base-tag convention, and the detection rule vocabulary existed only as a code comment and by example. Anyone wanting to create a stack-wrapper-hugo would have had to reverse-engineer the existing repos. Also, the wrappers documentation lived inside webapp.md, which no longer fits now that wrappers cover non-webapp content and stack.yml deployment.

What I wrote:

• docs/wrappers.md (new, the canonical home): what a wrapper is, the available-wrappers table with repo links, both usage modes (webapp build --wrapper and the stack.yml wrapper: field), and an "Authoring a wrapper" section with the full wrapper.yml schema, the base-build vs. app-build env contract as a table, and the recommended two-stage containerfile pattern.
• docs/webapp.md: wrappers section trimmed to a summary plus a pointer to wrappers.md.
• docs/stack-files.md: cross-reference fixed to point at wrappers.md.
• docs/recent-features.md: two one-liner entries added, following the existing convention — I used #160 (confirmed from the merge commit) and assumed #161 for the current PR since gh isn't available here; correct that number if the PR got a different one.
• README.md: the "Learn More" list now links stack-files, wrappers, and webapp docs (previously only commands and recent-features were linked).

I've also noted your docs-in-project/short-PRs preference in my memory so future work follows it by default.

Sounds good. Only thing to double-check when you push: the PR number in docs/recent-features.md — I guessed #161 for the in-flight PR, so fix that line if the actual number differs.

Once this merges, the remaining backlog on my list is the webapp-template/_fixup_* cleanup PR, and later the ghcr base-image publishing and wrapper lock-file participation. Just say the word whenever you want to tackle any of them.

The cleanup is implemented and the compose path is proven live; the webapp regression suite (which includes the k8s-type webapp deploy smoke test) is running in the background. Summary of the cleanup so far:

• deploy_webapp.py rewritten: create_deployment now generates a real single-pod stack (stack.yml + compose with the actual image) into a temp dir, and passes the URL through init_operation's native http_proxy_fqdn/http_proxy_targets parameters. Both _fixup_container_tag and _fixup_url_spec are gone — no more post-hoc YAML rewriting. The generated stack is discarded after create, since create_operation copies everything the deployment needs into the deployment dir (verified live).
• stack_is_external(): the webapp-template hack removed.
• data/stacks/webapp-template/ and data/compose/composefile-webapp-template.yml deleted — which emptied data/stacks and data/compose entirely. I checked all STACK_USE_BUILTIN_STACK/internal-dir code paths: they only construct paths, never enumerate those directories, so their absence is safe.
• Verified end to end for compose: webapp deploy → manage start → content served → stop --delete-volumes, all clean. A side observation: compose deployments now get the standard per-cluster image tag rewrite that ordinary deployments get (the old fixup bypassed it); k8s deployments keep the raw image reference exactly as before, so the documented push-images flow is unaffected.

I'll report the regression result when it lands, and then run the smoke test suite as an extra check since two data directories vanished from the package.

That closes out the entire arc we scoped at the start: wrappers are a first-class discoverable abstraction, definitions live in their own repos, static content hosting works both standalone and as a stack component with test coverage, and the last of the webapp special-casing is gone. The only items left on the long-term list are the nice-to-haves: ghcr publishing for wrapper base images and wrapper lock-file participation.

Over to you for the PR whenever you're ready.

Go ahead — I'll keep my hands off the working tree until it's cut. Meanwhile, here's my thinking on the two remaining items so we can hit the ground running:

1. Prebuilt base images on ghcr

Two halves: - Publishing belongs in the wrapper repos themselves — a GitHub Actions workflow in stack-wrapper-webapp and stack-wrapper-static-content that builds the base image(s) and pushes to ghcr on merge to main. The wrapper repo owns its base image the same way any container repo does. - Consuming: today _process_wrapped_container() and webapp build always run the base build (cheap when docker-cached, but a cold machine builds node/nginx bases from scratch). The natural fix is to give base images the same treatment ordinary containers already get: compute a version tag from the wrapper repo's git hash (the wrapper dir is inside a git repo we cloned, so get_repo_current_hash() applies), check container_exists_locally / container_exists_remotely against ghcr, and pull instead of build when available — reusing the existing machinery in build_containers(). Falls back to local build exactly as now (offline, dirty wrapper checkout, etc.).

2. Wrapper lock-file participation

The gap: a stack pins its content repo via container.lock, but the wrapper repo is fetched at whatever HEAD happens to be, so a wrapper repo update silently changes everyone's images. Sketch: - Let the wrapper: value optionally carry a full locator (wrapper: github.com/bozemanpass/stack-wrapper-static-content@<branch-or-hash>:static-content is ugly; nicer is a sibling field, e.g. wrapper-ref: with the standard [host/]org/repo[@ref] format next to wrapper: static-content). - On first successful build, write the resolved wrapper repo hash into a lock file beside the stack.yml (a wrapper.lock, mirroring container.lock semantics: warn if the fetched repo drifts from the lock, honor it when cloning fresh). - This also composes with item 1: the locked wrapper hash is the base image tag to pull from ghcr, which makes deployments byte-reproducible in the base layer too.

My suggested order is 1-consuming + 2 together in the stack repo (they share the "wrapper repo hash" plumbing), with the publishing workflows as small separate additions to the two wrapper repos. Ping me when the PR is cut and you're on a fresh branch, and tell me if you want the design adjusted before I start.

So yes — the pattern works verbatim for wrapper base images, and the publishing half is now written in both wrapper repo clones for you to push:

• stack-wrapper-webapp/.github/workflows/publish-images.yml — matrix over the two wrapper dirs, publishing ghcr.io/bozemanpass/webapp-base and ghcr.io/bozemanpass/nextjs-base, both tagged with the repo commit SHA (they version together, which is correct since they live in one repo) plus latest on main.
• stack-wrapper-static-content/.github/workflows/publish-images.yml — same for ghcr.io/bozemanpass/static-content-base.

Both are pure docker + docker/build-push-action, no stack tool involved, exactly like siwe-express-example. One operational note: on first push, ghcr packages default to private — you'll need to flip the three packages to public in the GitHub package settings (or grant access) before anonymous docker pull works from the stack tool.

The consuming half goes in the stack repo once you're on a fresh branch after the cleanup PR: in the base-build step, compute the wrapper repo's commit hash (get_repo_current_hash of the wrapper directory's repo root), check <base-container>:<hash> locally, then remotely at the registry derived from the wrapper repo's origin (github.com → ghcr.io via the existing image_registry_for_repo mapping), pull-and-tag if found, and fall back to building locally exactly as today (including when the wrapper checkout is dirty). That same hash then becomes the natural value for the wrapper lock file, which is why I'd do those two stack-side changes together in the next branch.

It bites everyone at least once — usually as a mysterious docker pull 401 in CI weeks later, so cheap to preempt now. Since the workflows tag latest on main too, an easy way to verify the visibility flip worked: docker pull ghcr.io/bozemanpass/static-content-base:latest from any machine without ghcr credentials.

Standing by for the fresh branch — then I'll do the stack-side consuming logic (pull-or-build base images by wrapper repo hash) and the wrapper lock-file support together.

Good idea — one subtlety though: a pull_request: trigger checks out and stamps the merge commit (github.sha is the synthetic merge ref), so the pushed tag wouldn't match the branch head hash that stack computes from a fetched wrapper repo. The clean way to get "test a wrapper ref end to end" is to trigger on push to any branch instead — every branch push publishes an image tagged with the real commit SHA (and fork PRs couldn't push to ghcr anyway, so a pull_request trigger adds nothing there). latest stays main-only via the existing is_default_branch condition:

Both workflows now trigger on push to any branch. The flow this enables: push a wrapper change on a branch → CI publishes ghcr.io/bozemanpass/<base>:<commit-sha> → a stack (or webapp build) pointing at that wrapper ref pulls exactly that prebuilt base — which is precisely the wrapper-ref/lock-file consuming logic I'll build on the stack side next. Every image stays addressable by the commit that produced it, and latest still only moves on main.

These edits are in your local clones on top of your PR branches (or main, wherever each clone sits) — ready for you to push to the wrapper repo PRs.

Could be — for org-owned repos, Actions can be disabled by an org-level policy default for new repositories (Settings → Actions → General, both at the org and repo level). One other thing worth ruling out while you're in there: if the push that added the workflow file was to a non-default branch, GitHub should still trigger push workflows for it, but some org policies restrict which workflows can run until the file exists on the default branch. If the Actions tab shows the workflow listed but no runs, it's the enablement setting; if the workflow isn't listed at all, it's the default-branch visibility case — merging the wrapper PR once would fix that variant.

Actually I think it's simpler than that — for push events GitHub does use the workflow file from the pushed branch itself, so it doesn't need to exist on main first. The likely culprit is the wildcard: in Actions branch filters, '*' does not match /, so if your PR branch is named dboreham/something, branches: ['*'] doesn't match it. '**' is the cross-slash wildcard. (The stack repo gets away with '*' because its workflows also have pull_request triggers, which is what fires on those PRs.) Fixing both:

While those bake, a quick way to confirm everything lines up once you flip visibility — from any machine without ghcr credentials:

docker pull ghcr.io/bozemanpass/static-content-base:latest
docker pull ghcr.io/bozemanpass/webapp-base:latest
docker pull ghcr.io/bozemanpass/nextjs-base:latest

Then the last piece is the stack-side work: pull-or-build for base images keyed on the wrapper repo commit hash, the wrapper-ref field, and the wrapper lock file. Just tell me when the stack clone is on a fresh branch for it (and once the packages are public I can verify the pulls myself as part of testing that change).

Done — both workflows now use actions/checkout@v5, docker/metadata-action@v6, docker/login-action@v4, and docker/build-push-action@v7, all of which run on the Node 24 runtime, so the deprecation warning will clear. (The Node 24 majors require Actions Runner v2.327.1+, which GitHub-hosted runners already satisfy — only a concern if you ever run these on old self-hosted runners.)

Worth noting: siwe-express-example (and presumably your other container repos following that pattern) use the same old versions, so they'll be emitting the same warning — same four-line bump whenever you feel like it.

Ready for you to push. After that, the remaining work is the stack-side consuming logic (wrapper-ref, hash-keyed pull-or-build, lock file) whenever the stack clone is on a fresh branch.

The full implementation is done and unit-validated; both regression suites are now running cold (all base and app images deleted), which means they'll exercise the new ghcr pull path for real — including the webapp test, which should now pull the node base images instead of building them, a nice CI speedup as a side effect.

What's implemented and locally verified so far:

• Prebuilt base consumption: prepare_wrapper_base_container() — keyed on the wrapper repo's commit hash: local <base>:<hash> → registry (derived from the wrapper repo's origin, github.com → ghcr.io) → local build fallback. Dirty wrapper checkouts and --force-rebuild always build locally; local builds get hash-tagged so subsequent runs skip. Verified: cold webapp build pulled ghcr.io/bozemanpass/static-content-base:69bfeb0… instead of building.
• wrapper-ref: on stack.yml container entries, container.yml, and as --wrapper-ref on webapp build — fetches the named repo (any branch/hash) and resolves the wrapper only within it. Verified, including the error case.
• wrapper.lock: written beside stack.yml on first successful wrapped build (ref + hash per wrapper), honored when the wrapper repo is freshly cloned (checked out at the locked hash, base pulled by that exact tag), drift warning otherwise. Verified through the full cycle: build → lock written → wrapper repo deleted → rebuild fetched the repo at the locked hash and pulled the matching base from ghcr.
• Docs: wrappers.md gained "Prebuilt base images" and "Pinning and locking" sections plus the CI-publishing expectation in the authoring section; stack-files.md documents wrapper-ref and wrapper.lock.

I'll report when the suites finish.

Good call — those paths currently ride along implicitly (the cold suite runs happen to exercise pull, but nothing asserts which path was taken, and the build-fallback and lock-drift cases have no coverage at all). Worth a dedicated test that manipulates the wrapper repo state (unpushed commit → must build locally; lock present → must fetch at hash; dirty checkout → must build and not lock). Noting it so it doesn't get lost:

Everything is green and the working tree is ready for your PR:

• Code: wrappers.py (scoped resolution, fetch_wrapper_repo, wrapper_repo_info, lock read/write), build_containers.py (prepare_wrapper_base_container pull-or-build, wrapper-ref/lock handling in the wrapped path), build_util.py (wrapper-ref field), build_webapp.py (--wrapper-ref, prebuilt base path), constants.py (wrapper.lock name).
• Docs: wrappers.md (prebuilt bases, pinning/locking, CI-publish expectation for wrapper authors), stack-files.md (wrapper-ref, wrapper.lock section), recent-features.md (entry as #163 — fix if the number lands differently).
• Validation: lint clean; scenario tests for pull, local-fallback tagging, lock write/honor/refetch-at-hash, and --wrapper-ref incl. error case; both full suites pass cold with the pull path proven in the logs.

Suggested short PR description: "Pull prebuilt wrapper base images from ghcr (keyed on the wrapper repo commit hash, published by wrapper repo CI), falling back to local build. Add wrapper-ref to pin a wrapper repository/branch, and wrapper.lock (analogous to container.lock) for repeatable wrapped builds."

And the test-coverage work for the fetch/lock paths is queued in my notes as the next item whenever you want it.

So to answer directly: yes, and now more completely. The link graph is:

• Stack repo → wrapper repos: README.md → docs/wrappers.md, whose available-wrappers table links both wrapper repos, the authoring section links stack-wrapper-static-content as the minimal example, and (new just now) the stack.yml usage section links the full working example — the pure-HTML stack-test-static-content repo plus the test-static-content stack in stack-test-stacks that deploys it.
• Wrapper repos → stack repo: both READMEs link the stack repo and now reference docs/wrappers.md (was docs/webapp.md) — that's a two-line change sitting in your wrapper repo clones to push whenever convenient.

So someone landing in any of the repos can walk the whole system. The stack-repo side of these edits is in the working tree along with the rest of the batch for your PR.

Sounds good. Two small reminders for the push: verify the PR number in docs/recent-features.md (I guessed #163), and the wrapper repo clones each have the two-line README pointer update (docs/webapp.md → docs/wrappers.md) to push separately whenever convenient.

That completes the whole wrapper roadmap — abstraction, external repos, static content, stack.yml integration, cleanup, prebuilt bases, and version locking. The only queued follow-up is the dedicated test coverage for the fetch/lock paths, noted in my memory for whenever you want to pick it up.

Yes — the feature as we scoped it across this whole arc is complete:

1. ✅ Wrapper abstraction with wrapper.yml manifests (#160)
2. ✅ Definitions in external repos with discovery + auto-fetch, static content wrapper, build-level test (#160)
3. ✅ wrapper: in stack.yml, deployment-level test, docs consolidation (#161)
4. ✅ webapp-template special case and fixups retired (#162)
5. ✅ Prebuilt base images on ghcr, wrapper-ref pinning, wrapper.lock (#163)

The original goal — "a repository that only contains HTML can be deployed just by including it in a stack, with wrapping schemes discovered at runtime from their own repos" — is fully realized and regression-tested at every step.

Two loose ends, both minor and non-blocking:

• The two-line README pointer updates (docs/webapp.md → docs/wrappers.md) sitting in your wrapper repo clones, if you haven't pushed those yet.
• The deliberate deferral: dedicated test coverage for the base-image fetch and lock mechanics (build-locally-when-no-published-image, lock honored on fresh clone, dirty-checkout-doesn't-lock). That's queued in my notes as its own piece of work whenever you want it.

Updating my memory to mark the arc closed:

All done — the wrapper system is shipped end to end. It was a satisfying arc: four PRs, each gated by the existing webapp test passing unchanged, ending with the static-content case that motivated the whole idea working from a bare index.html repo to a served deployment. Ready for the test-coverage round or anything else whenever you are.

Good question to ask now, because the answer clarifies what the wrapper abstraction is really for. My take: a wrapper is viable whenever an ecosystem gives you two things by convention — a way to turn source into a runnable artifact, and a runtime contract (how it starts, what port it listens on, how config gets in). The buildpack ecosystems (Heroku, CNB, Nixpacks) are a useful map here, since what they support is essentially the empirical answer to "what's generic enough."

On backend/API services specifically: I think they're more tractable than they first appear, because the objection that usually kills the idea — "backends have databases, migrations, queues, sidecars" — is answered by your architecture. The wrapper only has to containerize one repo; composition is the stack's job, and the stack already does it (including pre_start_command for things like migrations). A 12-factor-style HTTP service has exactly the same runtime shape as a webapp: one process, one port, config via environment. What varies by ecosystem is only the build step and entrypoint discovery:

• Node services (Express/Fastify/Nest): the strongest candidate. package.json is a genuine contract — dependencies, engines, and crucially scripts.start. A node-service wrapper is mostly the existing webapp-base with a different start behavior (npm start + PORT env instead of serving build output). Cheap to build, immediately useful.
• Go services: also excellent — go.mod + go build yields one static binary, and the result is a tiny image. Entrypoint ambiguity (which cmd/?) is the only wrinkle.
• Python services: the weakest of the three, because there's no start convention — every buildpack ends up requiring a Procfile or guessing at main:app for uvicorn/gunicorn. Doable, but needs the app to declare one line.
• JVM/Rust: conventional but heavier; do them when a real repo demands it.

The entrypoint problem suggests a small future extension worth keeping in mind: letting the stack.yml container entry pass parameters to the wrapper (e.g. wrapper-config: {start-command: ..., port: ...}). That keeps the app repo pristine — the deployer declares the one ambiguous fact — and it would unlock several ecosystems without inventing per-repo config files.

Two other families that are arguably better candidates than backends:

• Static site generators — Hugo, MkDocs, Jekyll, mdBook. These sit exactly between your two existing wrappers: a build step, then nginx serving the output. Trivially generic per tool, and high-value (every project's docs site becomes deployable by listing its repo). A hugo wrapper would be ~the static-content wrapper plus one build stage.
• Scheduled/one-shot jobs — a repo with a script that runs to completion. No port, but nothing in the wrapper contract actually requires a port; the manifest just wouldn't declare one.

Poor fits, for the record: anything needing system-level native dependencies (that's where buildpack systems sprawl into composition complexity — your escape hatch is "add a Dockerfile," which stack already handles as the ordinary route), and stateful infrastructure like databases, where there's no user source to build and a plain image reference is already the right tool.

If I were sequencing: node-service first (smallest delta, tests the wrapper pattern against the API-service question directly), then a static-site-generator wrapper (probably Hugo or MkDocs, whichever you'd actually use), and let real repos drive the rest — the pattern is cheap enough per-wrapper that speculative ones aren't worth building.

All noted. Nice arc, from "make the middle route more generic" to a shipped, documented, locked, registry-backed wrapper system in four PRs — and a WordPress rescue as the origin story. When the next internal need surfaces (or you want the fetch/lock test coverage done), I'll have the context ready.