backend-skeleton 1.0.0-beta.1

package/scripts/preflight-base-ref.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# D2: bash (not POSIX dash, not Node) for the preflight core.
+#   WHY: reusable outside this skill (drop into any repo or CI job) with zero package deps;
+#        bash is present on every machine/CI image we target, and the string/array handling
+#        needed for the 3-way default-branch cross-check is painful in strict POSIX sh.
+#   COST: won't run under `sh` on a minimal container without bash installed.
+#   EXIT: `bskel preflight --native` (lib/) reimplements this in Node if that ever bites.
+#
+# Verifies the current checkout is actually based on the repo's real default branch, not a
+# stale/abandoned one. Written after EnterWorktree's "fresh" mode branched a worktree off a
+# 658-commit-stale `origin/main` in a repo whose real default branch is `develop` -- this
+# script is the regression check for exactly that failure mode.
+#
+# Exit codes: 0 PASS | 10 NOT_A_REPO | 11 STALE_BASE | 12 WRONG_DEFAULT | 13 DIRTY | 14 BAD_ARGS
+#           | 18 REFRESH_FAILED (D-preflight-freshness, S3)
+set -euo pipefail
+
+MAX_BEHIND=0
+OFFLINE=0
+ALLOW_DIRTY=0
+JSON=0
+FETCH_TIMEOUT=60
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--max-behind) MAX_BEHIND="$2"; shift 2 ;;
+		# D-preflight-freshness (S3): --offline is the real name -- it means "I explicitly accept
+		# a local-only verdict, even if that means not knowing whether the remote has moved."
+		# --no-fetch is kept as an exact alias: it predates this item, is already documented in
+		# SKILL.md, this script's own header says it's "reusable outside this skill" (so an
+		# external caller may already depend on the old name), and 5 existing tests use it --
+		# removing it would be a needless breaking rename for a flag whose meaning didn't change.
+		--offline|--no-fetch) OFFLINE=1; shift ;;
+		--allow-dirty) ALLOW_DIRTY=1; shift ;;
+		--json) JSON=1; shift ;;
+		--fetch-timeout-seconds) FETCH_TIMEOUT="$2"; shift 2 ;;
+		*) echo "unknown argument: $1" >&2; exit 14 ;;
+	esac
+done
+
+# D-cli-contract (D2): a non-numeric --max-behind used to make the `[ "$BEHIND" -gt "$MAX_BEHIND" ]`
+# comparison below fail with a bash arithmetic error (status 2) rather than raise -- under
+# `set -euo pipefail` that error is INSIDE a conditional test, so the shell does not exit, and the
+# comparison is simply treated as false. That silently disabled this script's entire reason for
+# existing (the stale-base check) instead of refusing the bad argument. `bskel preflight` itself
+# now validates --max-behind before ever invoking this script, but this script is documented as
+# "reusable outside this skill" (see the file header) and must not rely on that caller alone.
+case "$MAX_BEHIND" in
+	''|*[!0-9]*) echo "--max-behind must be a non-negative whole number, got: $MAX_BEHIND" >&2; exit 14 ;;
+esac
+case "$FETCH_TIMEOUT" in
+	''|*[!0-9]*) echo "--fetch-timeout-seconds must be a non-negative whole number, got: $FETCH_TIMEOUT" >&2; exit 14 ;;
+esac
+
+# Minimal JSON string escaper (backslash, double-quote, control chars) so this script has
+# zero external deps -- not a general JSON encoder, just enough for the strings *this* script
+# builds itself (branch names, paths, our own messages).
+json_str() {
+	local s="$1"
+	s="${s//\\/\\\\}"
+	s="${s//\"/\\\"}"
+	s="${s//$'\n'/\\n}"
+	s="${s//$'\t'/\\t}"
+	printf '"%s"' "$s"
+}
+
+fail() {
+	code="$1"; reason="$2"; message="$3"
+	if [ "$JSON" -eq 1 ]; then
+		printf '{"verdict":"FAIL","reason":"%s","message":%s}\n' "$reason" "$(json_str "$message")"
+	else
+		echo "FAIL ($reason): $message" >&2
+	fi
+	exit "$code"
+}
+
+TOPLEVEL=$(git rev-parse --show-toplevel 2>/dev/null) || fail 10 NOT_A_REPO "not inside a git repository"
+cd "$TOPLEVEL"
+
+# D-preflight-freshness (S3): computed unconditionally now (previously skipped entirely under
+# --allow-dirty) so evidence can honestly distinguish "clean tree, passed" from "dirty tree,
+# --allow-dirty overrode it" -- both used to look identical in the recorded evidence.
+DIRTY_STATUS=$(git status --porcelain)
+WORKTREE_DIRTY="false"
+[ -n "$DIRTY_STATUS" ] && WORKTREE_DIRTY="true"
+if [ "$ALLOW_DIRTY" -eq 0 ] && [ "$WORKTREE_DIRTY" = "true" ]; then
+	fail 13 DIRTY "working tree is not clean (pass --allow-dirty to override)"
+fi
+
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+# Only extract an owner/repo pair when the remote is actually github.com -- a local path or
+# non-GitHub host must not be passed to `gh api`, both because it's meaningless and because
+# (found by test/preflight.test.mjs) `gh api` on a bogus path returns a 404 error BODY on
+# stdout with an exit code we must check, not just swallow with `|| true`.
+OWNER_REPO=""
+case "$REMOTE_URL" in
+	git@github.com:*) OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's#^git@github\.com:##; s#\.git$##') ;;
+	https://github.com/*) OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's#^https://github\.com/##; s#\.git$##') ;;
+esac
+
+# Three independent sources for "what is the real default branch" -- never assume `main`.
+# D-preflight-freshness (S3): each source's OUTCOME is now tracked explicitly (ok/failed/empty/
+# unavailable), not just its value -- a network failure silently produced the same empty string
+# as "this source doesn't apply here" before, so a repo whose only working source happened to be
+# the (possibly stale) local symbolic-ref cache could look identical to a repo that was properly
+# cross-checked. This does not turn a single-source resolution into a hard failure (see
+# D-preflight-freshness's EXIT in DECISIONS.md for why) -- it only makes that fact observable.
+SRC_SYMREF=""
+SYMREF_STATUS="absent"
+if SRC_SYMREF=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##') && [ -n "$SRC_SYMREF" ]; then
+	SYMREF_STATUS="ok"
+else
+	SRC_SYMREF=""
+fi
+
+SRC_REMOTE_SHOW=""
+REMOTE_SHOW_STATUS="failed"
+if REMOTE_SHOW_OUT=$(git remote show origin 2>/dev/null); then
+	SRC_REMOTE_SHOW=$(printf '%s\n' "$REMOTE_SHOW_OUT" | sed -n 's/^ *HEAD branch: //p')
+	if [ -n "$SRC_REMOTE_SHOW" ]; then REMOTE_SHOW_STATUS="ok"; else REMOTE_SHOW_STATUS="empty"; fi
+fi
+
+SRC_GH_API=""
+GH_API_STATUS="unavailable"
+if command -v gh >/dev/null 2>&1 && [ -n "$OWNER_REPO" ]; then
+	# Explicit exit-code check, NOT `$(...) || true` -- on a non-2xx response gh can print the
+	# error body (e.g. a 404 JSON payload with raw CRLFs) to stdout while exiting non-zero, and
+	# `|| true` alone would still let that garbage flow into SRC_GH_API.
+	if GH_API_OUT=$(gh api "repos/$OWNER_REPO" --jq .default_branch 2>/dev/null); then
+		SRC_GH_API="$GH_API_OUT"
+		GH_API_STATUS="ok"
+	else
+		GH_API_STATUS="failed"
+	fi
+fi
+
+SOURCES_OK=0
+for s in "$SYMREF_STATUS" "$REMOTE_SHOW_STATUS" "$GH_API_STATUS"; do
+	[ "$s" = "ok" ] && SOURCES_OK=$((SOURCES_OK + 1))
+done
+CROSS_CHECK_JSON=$(printf '{"sources_ok":%d,"symbolic_ref":"%s","remote_show":"%s","gh_api":"%s"}' "$SOURCES_OK" "$SYMREF_STATUS" "$REMOTE_SHOW_STATUS" "$GH_API_STATUS")
+
+CANDIDATES=""
+for c in "$SRC_SYMREF" "$SRC_REMOTE_SHOW" "$SRC_GH_API"; do
+	[ -n "$c" ] && CANDIDATES="$CANDIDATES $c"
+done
+UNIQUE=$(echo "$CANDIDATES" | tr ' ' '\n' | sed '/^$/d' | sort -u)
+UNIQUE_COUNT=$(echo "$UNIQUE" | sed '/^$/d' | wc -l | tr -d ' ')
+
+if [ "$UNIQUE_COUNT" -eq 0 ]; then
+	fail 12 WRONG_DEFAULT "could not determine default branch from origin/HEAD, 'git remote show origin', or 'gh api' -- refusing to assume 'main'"
+elif [ "$UNIQUE_COUNT" -gt 1 ]; then
+	fail 12 WRONG_DEFAULT "default-branch sources disagree: symbolic-ref='$SRC_SYMREF' remote-show='$SRC_REMOTE_SHOW' gh-api='$SRC_GH_API' -- resolve the discrepancy before proceeding, never guess"
+fi
+DEFAULT_BRANCH="$UNIQUE"
+
+# D-preflight-freshness (S3): fetch failure used to be swallowed entirely (`2>/dev/null || true`)
+# -- a genuinely offline/unreachable remote left this script computing `behind`/`ahead` against
+# whatever stale local `origin/<branch>` ref happened to already exist, and still reporting PASS.
+# Now: fetch is attempted unless --offline was given, and a failed attempt fails closed instead of
+# silently falling through to the (possibly very stale) cached ref. `http.lowSpeedLimit`/
+# `http.lowSpeedTime` bound a slow-but-connected transfer; a fully hung connection (or a non-http
+# transport that ignores those config keys, e.g. a local path or ssh remote) is bounded by the
+# Node-side `execFileSync` timeout in `bin/bskel.mjs::cmdPreflight` instead -- this script has no
+# portable `timeout(1)` to rely on (not present on macOS by default).
+FETCH_OUTCOME="skipped"
+FETCH_STATUS=""
+FETCH_STDERR=""
+if [ "$OFFLINE" -eq 0 ]; then
+	if FETCH_ERR=$(git -c "http.lowSpeedLimit=1000" -c "http.lowSpeedTime=$FETCH_TIMEOUT" fetch origin "$DEFAULT_BRANCH" --quiet 2>&1); then
+		FETCH_OUTCOME="ok"
+	else
+		FETCH_STATUS=$?
+		FETCH_STDERR=$(printf '%s\n' "$FETCH_ERR" | head -1)
+		fail 18 REFRESH_FAILED "could not refresh '$DEFAULT_BRANCH' from origin (git fetch exited $FETCH_STATUS: ${FETCH_STDERR:-no output}) -- fix connectivity, or re-run with --offline to accept a local-only verdict (it will be recorded as such)"
+	fi
+fi
+
+DEFAULT_REF="origin/$DEFAULT_BRANCH"
+git rev-parse --verify --quiet "$DEFAULT_REF" >/dev/null || fail 12 WRONG_DEFAULT "resolved default branch '$DEFAULT_BRANCH' has no ref '$DEFAULT_REF' locally (fetch failed or branch renamed)"
+ORIGIN_TIP_SHA=$(git rev-parse --verify --quiet "$DEFAULT_REF")
+
+HEAD_SHA=$(git rev-parse HEAD)
+BEHIND=$(git rev-list --count "HEAD..$DEFAULT_REF")
+AHEAD=$(git rev-list --count "$DEFAULT_REF..HEAD")
+MERGE_BASE=$(git merge-base HEAD "$DEFAULT_REF")
+DEFAULT_TIP_DATE=$(git log -1 --format=%ct "$DEFAULT_REF")
+MERGE_BASE_DATE=$(git log -1 --format=%ct "$MERGE_BASE")
+BASE_AGE_DAYS=$(( (DEFAULT_TIP_DATE - MERGE_BASE_DATE) / 86400 ))
+
+CURRENT_BRANCH=$(git branch --show-current)
+WORKTREE_PATH="$TOPLEVEL"
+CREATED_FROM=$(git reflog show "$CURRENT_BRANCH" 2>/dev/null | tail -1 || echo "")
+CHECKED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+POLICY_JSON=$(printf '{"max_behind":%d,"allow_dirty":%s,"offline":%s,"fetch_timeout_seconds":%d}' "$MAX_BEHIND" "$([ "$ALLOW_DIRTY" -eq 1 ] && echo true || echo false)" "$([ "$OFFLINE" -eq 1 ] && echo true || echo false)" "$FETCH_TIMEOUT")
+
+VERDICT="PASS"
+REASON=""
+if [ "$BEHIND" -gt "$MAX_BEHIND" ]; then
+	VERDICT="FAIL"
+	REASON="STALE_BASE"
+fi
+
+EVIDENCE_JSON=$(cat <<EOF
+{"default_branch":"$DEFAULT_BRANCH","source_of_truth":{"symbolic_ref":"$SRC_SYMREF","remote_show":"$SRC_REMOTE_SHOW","gh_api":"$SRC_GH_API"},"head_sha":"$HEAD_SHA","merge_base":"$MERGE_BASE","behind":$BEHIND,"ahead":$AHEAD,"base_age_days":$BASE_AGE_DAYS,"worktree_path":"$WORKTREE_PATH","current_branch":"$CURRENT_BRANCH","created_from":$(json_str "$CREATED_FROM"),"origin_tip_sha":$([ -n "$ORIGIN_TIP_SHA" ] && json_str "$ORIGIN_TIP_SHA" || echo null),"checked_at":"$CHECKED_AT","worktree_dirty":$WORKTREE_DIRTY,"fetch":"$FETCH_OUTCOME","policy":$POLICY_JSON,"cross_check":$CROSS_CHECK_JSON}
+EOF
+)
+
+if [ "$VERDICT" = "FAIL" ]; then
+	MSG="HEAD is $BEHIND commits behind $DEFAULT_REF (base is $BASE_AGE_DAYS days stale). Remediation: git worktree add <path> -b <branch> $DEFAULT_REF   (or, in-place: git rebase $DEFAULT_REF)"
+	if [ "$JSON" -eq 1 ]; then
+		printf '{"verdict":"FAIL","reason":"STALE_BASE","message":%s,"evidence":%s}\n' "$(json_str "$MSG")" "$EVIDENCE_JSON"
+	else
+		echo "FAIL (STALE_BASE): $MSG" >&2
+		echo "evidence: $EVIDENCE_JSON" >&2
+	fi
+	exit 11
+fi
+
+if [ "$JSON" -eq 1 ]; then
+	printf '{"verdict":"PASS","evidence":%s}\n' "$EVIDENCE_JSON"
+else
+	echo "PASS: HEAD is up to date with $DEFAULT_REF (behind=$BEHIND, ahead=$AHEAD)"
+fi
+exit 0

package/stack/apply.mjs

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import Ajv2020 from 'ajv/dist/2020.js';
+// P2b (D-greenfield-parameters): was a private `renderTemplate(templatePath, vars)` here, moved to
+// lib/template.mjs unchanged once `new/fastapi.mjs` became its second real consumer.
+import { renderTemplateFile } from '../lib/template.mjs';
+
+const STACK_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_ROOT = path.join(STACK_ROOT, '..', 'schemas');
+
+// D-security-4: `choiceId` must be a bare identifier, never a path. Found by the Codex security
+// review: `path.join(STACK_ROOT, 'catalog', choiceId + '.yml')` with an unvalidated choiceId
+// lets `--choice ../../../../whatever` escape the catalog dir entirely.
+const CHOICE_ID_RE = /^[a-z][a-z0-9-]*$/;
+
+export function listCatalogChoices() {
+	const catalogDir = path.join(STACK_ROOT, 'catalog');
+	if (!fs.existsSync(catalogDir)) return [];
+	return fs.readdirSync(catalogDir)
+		.filter((f) => f.endsWith('.yml'))
+		.map((f) => f.replace(/\.yml$/, ''));
+}
+
+// Resolves `target` and asserts it stays within `root` -- used for both catalog-entry template
+// paths (must stay under STACK_ROOT) and generated-file target paths (must stay under the
+// caller's repoRoot). A catalog entry is data (currently only ships with this skill, but the
+// mechanism doesn't assume that), so every path it names is treated as untrusted input.
+function assertContained(root, target, label) {
+	const resolvedRoot = path.resolve(root);
+	const resolvedTarget = path.resolve(target);
+	const rel = path.relative(resolvedRoot, resolvedTarget);
+	if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+		throw new Error(`${label} "${target}" escapes "${root}" -- refusing (possible path traversal in a stack catalog entry)`);
+	}
+}
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) _ajv = new Ajv2020({ allErrors: true, strict: false });
+	return _ajv;
+}
+
+function loadStackChoiceSchema() {
+	return JSON.parse(fs.readFileSync(path.join(SCHEMAS_ROOT, 'stack-choice.schema.json'), 'utf8'));
+}
+
+export function loadCatalogEntry(choiceId) {
+	if (!CHOICE_ID_RE.test(choiceId)) {
+		throw new Error(`invalid stack choice "${choiceId}" -- must match ${CHOICE_ID_RE} (known choices: ${listCatalogChoices().join(', ') || '(none)'})`);
+	}
+	const catalogPath = path.join(STACK_ROOT, 'catalog', `${choiceId}.yml`);
+	assertContained(path.join(STACK_ROOT, 'catalog'), catalogPath, 'catalog entry path');
+	if (!fs.existsSync(catalogPath)) {
+		throw new Error(`unknown stack choice "${choiceId}" -- known choices: ${listCatalogChoices().join(', ') || '(none)'}`);
+	}
+	const entry = parseYaml(fs.readFileSync(catalogPath, 'utf8'));
+
+	const schema = loadStackChoiceSchema();
+	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	if (!validateFn(entry)) {
+		const details = (validateFn.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
+		throw new Error(`catalog entry "${choiceId}.yml" does not match schemas/stack-choice.schema.json: ${details}`);
+	}
+	return entry;
+}
+
+// D7 (DECISIONS.md): a stack choice's static half is entirely data-driven (this catalog entry)
+// -- planApply/applyPlan are generic across any catalog entry shaped like schemas/stack-choice.
+// schema.json, so "add a stack" is a YAML edit (+ optionally a template), not new glue code.
+export function planApply(repoRoot, entry, { port = 8080 } = {}) {
+	const plan = { choice: entry.id, alreadyDetected: false, files: [], envExampleActions: [], configChecks: [] };
+
+	// D-security-6: never read the target repo's .env, even for a read-only dry-run detection
+	// check. This project's own convention (D-security-6 in DECISIONS.md) and the target repo's CLAUDE.md
+	// both say the agent doesn't read/edit .env -- only a human-invoked runtime bootstrap script
+	// does. Detection now relies solely on `detect.files` (e.g. does scripts/dev-tunnel.sh
+	// already exist), which is what the ngrok catalog entry primarily uses anyway. Found by the
+	// Codex security review (a dry-run reading the full .env, even without printing it, still
+	// crossed the stated boundary).
+	plan.alreadyDetected = (entry.detect?.files ?? []).some((f) => fs.existsSync(path.join(repoRoot, f)));
+
+	for (const f of entry.static?.files ?? []) {
+		const templatePath = path.join(STACK_ROOT, f.template);
+		assertContained(STACK_ROOT, templatePath, 'catalog template path');
+		const targetPath = path.join(repoRoot, f.path);
+		assertContained(repoRoot, targetPath, 'catalog target path');
+		const rendered = renderTemplateFile(templatePath, { PORT: port });
+		const exists = fs.existsSync(targetPath);
+		const unchanged = exists && fs.readFileSync(targetPath, 'utf8') === rendered;
+		plan.files.push({
+			path: f.path,
+			mode: f.mode ?? null,
+			action: !exists ? 'create' : (unchanged ? 'unchanged' : 'update'),
+			content: rendered,
+		});
+	}
+
+	const envExamplePath = path.join(repoRoot, '.env.example');
+	const existingEnvExample = fs.existsSync(envExamplePath) ? fs.readFileSync(envExamplePath, 'utf8') : '';
+	for (const e of entry.static?.env_example ?? []) {
+		const already = new RegExp(`^${e.key}=`, 'm').test(existingEnvExample);
+		plan.envExampleActions.push({
+			key: e.key, doc: e.doc, required: Boolean(e.required), secret: Boolean(e.secret),
+			action: already ? 'unchanged' : 'append',
+		});
+	}
+
+	for (const c of entry.static?.config_check ?? []) {
+		const targetPath = path.join(repoRoot, c.target);
+		assertContained(repoRoot, targetPath, 'catalog config_check target path');
+		let status = 'target-missing';
+		if (fs.existsSync(targetPath)) {
+			status = new RegExp(c.externalized_pattern).test(fs.readFileSync(targetPath, 'utf8'))
+				? 'already-externalized'
+				: 'needs-manual-patch';
+		}
+		plan.configChecks.push({ target: c.target, status, note: c.note });
+	}
+
+	return plan;
+}
+
+// D-config-patch: config_check is informational ONLY -- backend-skeleton never auto-edits an
+// application config file. WHY: the target config (e.g. Spring's application.yaml) is often
+// comment-dense and hand-tuned; a wrong automatic edit there is a worse failure mode than
+// asking a human to add one line. COST: a `needs-manual-patch` status requires a human step.
+// EXIT: if a safe, comment-preserving patcher is built later (the `yaml` package's Document
+// API supports this), config_check could gain an `apply` action -- not built now because the
+// real target (Team-IZ-Backend) doesn't need it (already externalized), so there's no concrete
+// case to validate a patcher against yet.
+export function applyPlan(repoRoot, plan) {
+	const written = [];
+	for (const f of plan.files) {
+		if (f.action === 'unchanged') continue;
+		const targetPath = path.join(repoRoot, f.path);
+		// Re-asserted here too (planApply already checked it) -- applyPlan must not assume it's
+		// only ever called with a plan it just generated for the same repoRoot.
+		assertContained(repoRoot, targetPath, 'catalog target path');
+		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+		fs.writeFileSync(targetPath, f.content);
+		if (f.mode) fs.chmodSync(targetPath, Number.parseInt(f.mode, 8));
+		written.push(f.path);
+	}
+
+	const toAppend = plan.envExampleActions.filter((a) => a.action === 'append');
+	if (toAppend.length > 0) {
+		const envExamplePath = path.join(repoRoot, '.env.example');
+		let addition = fs.existsSync(envExamplePath) ? '' : '# Environment variables -- copy relevant ones into your own .env.\n\n';
+		for (const a of toAppend) {
+			addition += `# ${a.doc}${a.required ? ' (required)' : ' (optional)'}\n${a.key}=\n\n`;
+		}
+		fs.appendFileSync(envExamplePath, addition);
+		written.push('.env.example');
+	}
+
+	return written;
+}

package/stack/bootstrap/_lib.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Shared helpers for backend-skeleton stack bootstrap scripts. Copied into the target repo
+# alongside the script that sources it (see stack/apply.mjs) -- self-contained, no dependency
+# on backend-skeleton being installed at runtime.
+
+# Polls a JSON endpoint (e.g. ngrok's local API) once a second until it returns a body
+# containing `"public_url"`, or times out. Whole-second granularity is deliberate -- a tunnel
+# typically comes up in 1-3s, and this only needs to be "prompt", not "instant".
+wait_for_tunnel() {
+	local url="$1" timeout_s="$2" waited=0
+	while [ "$waited" -lt "$timeout_s" ]; do
+		local body
+		# --connect-timeout/--max-time bound EACH poll attempt -- without these, a port that
+		# accepts-but-never-responds (or certain firewalled/unusual ports) can make a single
+		# curl call hang far longer than $timeout_s, defeating the outer loop's bound entirely.
+		body=$(curl -sf --connect-timeout 2 --max-time 3 "$url" 2>/dev/null || true)
+		if [ -n "$body" ] && echo "$body" | grep -q '"public_url"'; then
+			echo "$body"
+			return 0
+		fi
+		sleep 1
+		waited=$((waited + 1))
+	done
+	return 1
+}
+
+# Extracts the first https public_url from an ngrok /api/tunnels response. grep+sed, not a
+# JSON parser -- the response shape (`"public_url":"https://..."` as a flat string field) is
+# stable enough for this and avoids a jq/python dependency in a script meant to be portable.
+extract_https_url() {
+	echo "$1" | grep -o '"public_url":"https://[^"]*"' | head -1 | sed -E 's/.*"(https:\/\/[^"]*)".*/\1/'
+}
+
+# Idempotent: replaces `KEY=...` if the line already exists, appends a new line if not.
+#
+# D-security-5: `.env` holds real secrets (NGROK_AUTHTOKEN and whatever else the target app
+# needs), so this must never leave it more exposed than it started. Two fixes here, found by the
+# Codex security review:
+#   1. `mktemp`, not a predictable `${file}.$$.tmp` name -- the PID-based name let another local
+#      process race a symlink into that exact path before the `mv` lands.
+#   2. `chmod 600` unconditionally after every write -- shell redirection creates the temp file
+#      at the process umask (0644 under a typical 022 umask), and `mv` then replaced .env with
+#      that laxer-mode file, silently downgrading it from whatever it was (normally 0600).
+env_upsert() {
+	local file="$1" key="$2" value="$3"
+	touch "$file"
+	if grep -q "^${key}=" "$file" 2>/dev/null; then
+		local tmp
+		tmp=$(mktemp "${file}.XXXXXX")
+		sed "s|^${key}=.*|${key}=${value}|" "$file" > "$tmp" && mv "$tmp" "$file"
+	else
+		echo "${key}=${value}" >> "$file"
+	fi
+	chmod 600 "$file"
+}
+
+# Appends `value` to a comma-separated `KEY=a,b,c` value, only if not already present verbatim
+# (used for AUTH_LOGIN_ALLOWED_ORIGINS -- re-running the tunnel script with the same ephemeral
+# URL, or restarting with a reserved domain that's already listed, must not duplicate entries).
+env_append_unique() {
+	local file="$1" key="$2" value="$3"
+	touch "$file"
+	local current
+	current=$(grep "^${key}=" "$file" 2>/dev/null | head -1 | cut -d= -f2-)
+	if [ -z "$current" ]; then
+		env_upsert "$file" "$key" "$value"
+		return
+	fi
+	case ",$current," in
+		*",$value,"*) return ;;
+	esac
+	env_upsert "$file" "$key" "${current},${value}"
+}

package/stack/bootstrap/ngrok.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Generated by backend-skeleton (stack choice: ngrok). Self-contained in this repo -- does not
+# require backend-skeleton to be installed to run. See scripts/_bskel-lib.sh for shared helpers.
+#
+# D-ngrok: ephemeral vs. reserved-domain mode is switched by whether NGROK_DOMAIN is set --
+# not a fixed choice made at codegen time. D8 (DECISIONS.md): this script writes .env; the
+# agent that ran `bskel stack apply` never touches .env directly -- only a human-invoked
+# runtime script does, per CLAUDE.md's ".env is never read/edited by the agent" rule.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+source scripts/_bskel-lib.sh
+
+# D-cli-contract (D2): {{PORT}} is substituted by stack/apply.mjs's renderTemplate() at `bskel
+# stack apply --port N` time -- before this, the template had no substitution site for the PORT
+# variable planApply() already computed and passed in, so --port silently had zero effect no
+# matter what value was given (the deployed default was always literally 8080). This only sets
+# the DEFAULT baked into the deployed script -- a human re-running it later can still override
+# with the script's own runtime `--port` flag (line below), unchanged.
+PORT="${PORT:-{{PORT}}}"
+ENV_FILE=".env"
+EXEC_CMD=""
+PRINT_ONLY=0
+TIMEOUT_S=30
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--port) PORT="$2"; shift 2 ;;
+		--exec) EXEC_CMD="$2"; shift 2 ;;
+		--print-only) PRINT_ONLY=1; shift ;;
+		--timeout) TIMEOUT_S="$2"; shift 2 ;;
+		*) echo "unknown argument: $1" >&2; exit 14 ;;
+	esac
+done
+
+: "${NGROK_AUTHTOKEN:?NGROK_AUTHTOKEN not set -- see .env.example, get one at https://dashboard.ngrok.com/get-started/your-authtoken}"
+
+NGROK_ARGS=(http "$PORT" --log=stdout)
+if [ -n "${NGROK_DOMAIN:-}" ]; then
+	echo "using reserved domain: $NGROK_DOMAIN"
+	NGROK_ARGS+=(--domain "$NGROK_DOMAIN")
+else
+	echo "no NGROK_DOMAIN set -- using an ephemeral URL (different every run)"
+fi
+
+# D-security-5: mktemp, not a predictable /tmp/bskel-ngrok-$$.log name -- the PID-based name
+# let another local process race a symlink into that exact path before ngrok's stdout/stderr
+# ever gets written to it. Found by the Codex security review.
+LOG_FILE=$(mktemp "${TMPDIR:-/tmp}/bskel-ngrok-XXXXXX.log")
+ngrok "${NGROK_ARGS[@]}" > "$LOG_FILE" 2>&1 &
+NGROK_PID=$!
+mkdir -p .sbf 2>/dev/null || true
+echo "$NGROK_PID" > .sbf/ngrok.pid 2>/dev/null || true
+
+cleanup() {
+	kill "$NGROK_PID" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+echo "waiting for ngrok tunnel (up to ${TIMEOUT_S}s)..."
+TUNNEL_JSON=$(wait_for_tunnel "http://127.0.0.1:4040/api/tunnels" "$TIMEOUT_S") || {
+	echo "ngrok did not come up within ${TIMEOUT_S}s -- log:" >&2
+	cat "$LOG_FILE" >&2
+	exit 1
+}
+PUBLIC_URL=$(extract_https_url "$TUNNEL_JSON")
+if [ -z "$PUBLIC_URL" ]; then
+	echo "could not extract an https tunnel URL from ngrok's API response: $TUNNEL_JSON" >&2
+	exit 1
+fi
+echo "tunnel up: $PUBLIC_URL"
+
+if [ "$PRINT_ONLY" -eq 1 ]; then
+	echo "$PUBLIC_URL"
+	exit 0
+fi
+
+# Spring reads .env only at boot (spring.config.import) -- writing these AFTER the app has
+# already started does nothing until the next restart. That's why this script's default mode
+# is "write env, then tell you to (re)start", and --exec exists for a one-shot tunnel-then-run.
+env_upsert "$ENV_FILE" PUBLIC_BASE_URL "$PUBLIC_URL"
+env_append_unique "$ENV_FILE" AUTH_LOGIN_ALLOWED_ORIGINS "$PUBLIC_URL"
+echo "wrote PUBLIC_BASE_URL and appended to AUTH_LOGIN_ALLOWED_ORIGINS in $ENV_FILE"
+
+if [ -n "$EXEC_CMD" ]; then
+	echo "starting: $EXEC_CMD"
+	exec $EXEC_CMD
+fi
+
+echo "tunnel is running (pid $NGROK_PID) -- (re)start your app now to pick up the env vars just written."
+wait "$NGROK_PID"

package/stack/catalog/ngrok.yml

@@ -0,0 +1,63 @@
+id: ngrok
+description: >
+  Expose the local dev server through an ngrok tunnel -- ephemeral URL by default, or a
+  reserved domain if NGROK_DOMAIN is set (paid ngrok plan). For webhook testing or sharing a
+  running instance without deploying. See D-ngrok in DECISIONS.md: both modes are supported by
+  the same script, switched purely by whether NGROK_DOMAIN is present in the environment --
+  this is not a fixed choice baked in at codegen time.
+
+detect:
+  files:
+    - scripts/dev-tunnel.sh
+  env_keys:
+    - NGROK_AUTHTOKEN
+
+static:
+  files:
+    - path: scripts/dev-tunnel.sh
+      template: bootstrap/ngrok.sh
+      mode: "755"
+    - path: scripts/_bskel-lib.sh
+      template: bootstrap/_lib.sh
+      mode: "644"
+
+  env_example:
+    - key: NGROK_AUTHTOKEN
+      required: true
+      secret: true
+      doc: "ngrok authtoken -- https://dashboard.ngrok.com/get-started/your-authtoken"
+    - key: NGROK_DOMAIN
+      required: false
+      doc: "reserved domain (paid ngrok plan). Unset = ephemeral URL, different every run."
+    - key: PUBLIC_BASE_URL
+      required: false
+      doc: "written automatically by scripts/dev-tunnel.sh once the tunnel is confirmed up -- do not set this by hand, it will be overwritten"
+
+  config_check:
+    - target: src/main/resources/application.yaml
+      externalized_pattern: "\\$\\{AUTH_LOGIN_ALLOWED_ORIGINS"
+      note: >
+        allowed-origins must be environment-variable-driven for the tunnel URL to actually take
+        effect (e.g. `allowed-origins: ${AUTH_LOGIN_ALLOWED_ORIGINS:default-value}`). If this
+        check reports needs-manual-patch, add that yourself -- backend-skeleton deliberately
+        does not auto-edit application config files (see D-config-patch in DECISIONS.md).
+
+runtime:
+  script: scripts/dev-tunnel.sh
+  # D5: binaries scripts/dev-tunnel.sh (bootstrap/ngrok.sh) and its shared lib actually shell out
+  # to at runtime -- ngrok itself, plus curl (bootstrap/_lib.sh's wait_for_tunnel). `bskel stack
+  # apply` never runs either of these itself; `bskel doctor --workflow stack` reads this field to
+  # tell a human what the SCRIPT it's about to generate will need, before they hit a missing-
+  # binary failure mid-tunnel-setup.
+  requires:
+    - ngrok
+    - curl
+  readiness:
+    probe: "http://127.0.0.1:4040/api/tunnels"
+  produces:
+    - key: PUBLIC_BASE_URL
+      sink: env
+      mode: set
+    - key: AUTH_LOGIN_ALLOWED_ORIGINS
+      sink: env
+      mode: append-unique