backend-skeleton 1.0.0-beta.1

package/new/spring.mjs

@@ -0,0 +1,198 @@
+// P2 (D-greenfield-bootstrap): the only `bskel` command that talks to a network service --
+// Spring Initializr's own public `start.spring.io` REST API (the same one behind `spring init`/
+// the start.spring.io web UI). Every other command in this tool is pure local git/fs, so this is
+// a genuinely new risk category: never auto-triggered by any other command, always a single
+// explicit invocation, and `--offline` refuses cleanly instead of hanging on a dead connection.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+// "Pinned" means the DEFAULT DEPENDENCY SET is a named, reviewable constant here, not a live query
+// against whatever Initializr's own current defaults happen to be today -- the same dependency
+// set test/fixtures/java-compile/build.gradle and the real oracle repo both already use
+// (web, data-jpa, security, validation, lombok), so a freshly scaffolded project is immediately
+// compatible with every other `bskel` command (handles codegen, contract emit's Bean Validation
+// assumptions, etc.) with zero extra setup. `javaVersion` matches this whole tool's established
+// Java 17 baseline (CLAUDE.md's own documented oracle-repo toolchain). Deliberately does NOT pin
+// an exact `bootVersion` -- Spring Initializr only serves actively-supported versions and ages
+// old ones out on its own schedule, so a hardcoded exact version is a maintenance liability here
+// (unlike a gate token, where rigidity is the safety property); this tool's own Jackson-package
+// detection (handles/providers/java-spring/emit.mjs's detectJacksonPackage) already adapts to
+// whichever major version Initializr hands back, Boot 3 or 4.
+//
+// P2b (D-greenfield-parameters): these are now DEFAULTS a caller can override, not hardcodes. The
+// pinning argument above survives intact -- what it was ever protecting is "bskel does not silently
+// track Initializr's moving defaults", not "a user may not state their own group id".
+export const BASE_DEPENDENCIES = Object.freeze(['web', 'data-jpa', 'security', 'validation', 'lombok']);
+export const DEFAULT_JAVA_VERSION = '17';
+export const DEFAULT_GROUP_ID = 'com.example';
+
+const INITIALIZR_URL = 'https://start.spring.io/starter.zip';
+
+// P2b: the three baseline dependencies OTHER `bskel` commands actually require downstream. Dropping
+// `security` or `lombok` degrades nothing bskel itself does, so neither is warned about.
+const REQUIRED_FOR_BSKEL = Object.freeze({
+	web: 'without `web` the project has no @RestController/@RequestMapping endpoints at all, so `bskel scan`\'s java-spring adapter finds no controllers and `bskel contract emit` has nothing to build operations from',
+	'data-jpa': 'without `data-jpa` the project has no @Entity classes, so the java-spring adapter reports zero resources and `bskel handles plan` approves nothing (resource.fetch has nothing to fetch)',
+	validation: 'without `validation` the resolver `bskel handles emit` generates will not compile -- its patchField() imports jakarta.validation.Validator / ConstraintViolation (see D-patch-strategy)',
+});
+
+function splitDependencyList(raw, flag) {
+	const ids = String(raw).split(',').map((s) => s.trim()).filter((s) => s !== '');
+	if (ids.length === 0) {
+		throw new Error(`--${flag} was given no usable dependency ids (got ${JSON.stringify(raw)}) -- pass a comma-separated list of start.spring.io dependency ids, e.g. --${flag} actuator,postgresql`);
+	}
+	return [...new Set(ids)];
+}
+
+// P2b (D-greenfield-parameters), user decision: `--dependencies` REPLACES the baseline five rather
+// than adding to them. That is deliberately the more dangerous of the two semantics -- so the danger
+// is made VISIBLE (a specific, named warning per missing baseline dependency, naming what breaks)
+// rather than prevented. `--add-dependencies` is the additive-only flag for the common case; it
+// cannot drop anything, so it never warns. Mutually exclusive -- merging their semantics would make
+// "did I replace or extend?" un-answerable from the command line alone.
+//
+// Pure: returns the resolved set plus the warnings, so the caller decides where they go (stderr,
+// per this CLI's own contract that warnings are never suppressed by --quiet or --json).
+export function resolveSpringDependencies({ dependencies = null, addDependencies = null } = {}) {
+	if (dependencies != null && addDependencies != null) {
+		throw new Error('--dependencies and --add-dependencies are mutually exclusive -- --dependencies REPLACES the baseline set (web, data-jpa, security, validation, lombok), --add-dependencies extends it');
+	}
+
+	let resolved;
+	if (dependencies != null) {
+		resolved = splitDependencyList(dependencies, 'dependencies');
+	} else if (addDependencies != null) {
+		resolved = [...new Set([...BASE_DEPENDENCIES, ...splitDependencyList(addDependencies, 'add-dependencies')])];
+	} else {
+		resolved = [...BASE_DEPENDENCIES];
+	}
+
+	const warnings = [];
+	for (const [id, consequence] of Object.entries(REQUIRED_FOR_BSKEL)) {
+		if (resolved.includes(id)) continue;
+		warnings.push(`warning: the requested dependency set does not include \`${id}\` -- ${consequence}. Scaffolding anyway (you asked for this set explicitly); add it with \`--add-dependencies ${id}\` if that was not intended.`);
+	}
+	return { dependencies: resolved, warnings };
+}
+
+// Java package names can't contain hyphens -- `demo-app` becomes `demoapp`, matching the
+// convention `handles/providers/java-spring/plan.mjs::detectBasePackage()` itself would derive
+// from the resulting *Application.java's own package declaration.
+//
+// P2b: every parameter below is optional and defaults to exactly what P2 hardcoded, so calling this
+// with only `{ slug }` produces a BYTE-IDENTICAL url to the pre-P2b one -- including query-parameter
+// ORDER, which is why the four optional keys are appended after the original eight rather than
+// interleaved. `test/new-cli.test.mjs` pins that string exactly.
+export function buildInitializrUrl({
+	slug,
+	groupId = DEFAULT_GROUP_ID,
+	artifactId = null,
+	packageName = null,
+	name = null,
+	description = null,
+	projectVersion = null,
+	javaVersion = DEFAULT_JAVA_VERSION,
+	packaging = null,
+	dependencies = BASE_DEPENDENCIES,
+} = {}) {
+	const packageSuffix = slug.replace(/-/g, '');
+	const params = new URLSearchParams({
+		type: 'gradle-project',
+		language: 'java',
+		javaVersion,
+		groupId,
+		artifactId: artifactId ?? slug,
+		name: name ?? slug,
+		packageName: packageName ?? `${groupId}.${packageSuffix}`,
+		dependencies: [...dependencies].join(','),
+	});
+	// Never sent unless explicitly asked for: an omitted parameter lets Initializr apply its own
+	// current default, which is the same reason `bootVersion` is never sent at all.
+	if (packaging != null) params.set('packaging', packaging);
+	if (description != null) params.set('description', description);
+	if (projectVersion != null) params.set('version', projectVersion);
+	return `${INITIALIZR_URL}?${params.toString()}`;
+}
+
+// Initializr answers a bad `dependencies`/`type`/`packaging`/`language` with a clean, quotable JSON
+// body: {"timestamp":...,"status":400,"error":"Bad Request","message":"Unknown dependency
+// 'not-a-real-dep' check project metadata","path":"/starter.zip"} (measured 2026-08-23). Surfacing
+// that `message` verbatim is what makes pass-through validation an honest choice for those four
+// parameters instead of a shrug. Defensive on every step: a mocked/odd response object without
+// .json() must not turn a clean HTTP error into a TypeError.
+async function describeHttpFailure(response) {
+	if (typeof response.json !== 'function') return null;
+	try {
+		const body = await response.json();
+		const message = body?.message;
+		return typeof message === 'string' && message !== '' ? message : null;
+	} catch {
+		return null;
+	}
+}
+
+// `--offline` (or no network at all) must fail with a clear, actionable message -- never hang or
+// produce a raw fetch stack trace. Mirrors `bskel preflight --offline`'s own precedent for the
+// no-network case.
+export async function scaffoldSpring({
+	dir,
+	slug,
+	offline = false,
+	groupId = DEFAULT_GROUP_ID,
+	artifactId = null,
+	packageName = null,
+	name = null,
+	description = null,
+	projectVersion = null,
+	javaVersion = DEFAULT_JAVA_VERSION,
+	packaging = null,
+	dependencies = BASE_DEPENDENCIES,
+}) {
+	if (offline) {
+		throw new Error('bskel new --stack spring requires network access (calls start.spring.io) -- re-run without --offline, or use --stack fastapi (fully local, no network call)');
+	}
+	if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) {
+		throw new Error(`${dir} already exists and is not empty -- refusing to scaffold into it`);
+	}
+
+	const url = buildInitializrUrl({ slug, groupId, artifactId, packageName, name, description, projectVersion, javaVersion, packaging, dependencies });
+	let response;
+	try {
+		response = await fetch(url);
+	} catch (err) {
+		throw new Error(`could not reach start.spring.io (${err.message}) -- check network access, or use --stack fastapi (fully local, no network call)`);
+	}
+	if (!response.ok) {
+		const detail = await describeHttpFailure(response);
+		throw new Error(`start.spring.io returned ${response.status} ${response.statusText}${detail ? ` -- it said: ${detail}` : ''} -- the request was: ${url}`);
+	}
+	const zipBytes = Buffer.from(await response.arrayBuffer());
+
+	fs.mkdirSync(dir, { recursive: true });
+	const zipPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'bskel-new-spring-')), `${slug}.zip`);
+	fs.writeFileSync(zipPath, zipBytes);
+	try {
+		// P2b: `baseDir` is deliberately NEVER sent to Initializr and is deliberately NOT exposed as
+		// a flag. With no baseDir the archive is FLAT (build.gradle/settings.gradle/src/gradlew at the
+		// root), which is exactly what this extraction assumes -- setting it would nest the whole
+		// project one level down and silently break every downstream adapter's detect(), which look
+		// for `build.gradle` + `src/main/java` at the repo root. Pinned by a regression test.
+		execFileSync('unzip', ['-q', zipPath, '-d', dir]);
+	} catch (err) {
+		throw new Error(`could not extract the downloaded project (is \`unzip\` on PATH?): ${err.message}`);
+	} finally {
+		fs.rmSync(path.dirname(zipPath), { recursive: true, force: true });
+	}
+
+	return {
+		dir,
+		dependencies: [...dependencies],
+		javaVersion,
+		groupId,
+		artifactId: artifactId ?? slug,
+		packageName: packageName ?? `${groupId}.${slug.replace(/-/g, '')}`,
+		packaging,
+	};
+}

package/new/templates/fastapi/README.md

@@ -0,0 +1,26 @@
+# {{NAME}}
+
+{{DESCRIPTION_BLOCK}}Scaffolded by `bskel new --stack fastapi`.
+
+## Run it
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+fastapi dev app/main.py --port {{PORT}}     # or: uvicorn app.main:app --reload --port {{PORT}}
+```
+
+Then check http://127.0.0.1:{{PORT}}/health
+
+{{DATABASE_SECTION}}## Next steps
+
+This is a local-only git repository with one commit. `bskel preflight` needs a real `origin`
+remote with a resolvable default branch, so:
+
+```bash
+gh repo create <name> --private --source=. --push   # or push to a remote you already own
+git remote set-head origin --auto
+bskel preflight
+```
+
+From there, `bskel status` / `bskel next` will tell you what to run.

package/new/templates/fastapi/app/main.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI(title="{{NAME}}")
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}

package/new/templates/fastapi/gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+specs/
+.sbf/

package/new/templates/fastapi/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "{{NAME}}"
+version = "{{PROJECT_VERSION}}"
+description = "{{DESCRIPTION}}"
+{{LICENSE_LINE}}requires-python = "{{REQUIRES_PYTHON}}"
+dependencies = [
+    "fastapi[standard]>=0.115.0,<1.0.0",
+    "sqlmodel>=0.0.22",
+    "uvicorn[standard]>=0.30.0",
+{{DATABASE_DEPENDENCY_LINES}}]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "backend-skeleton",
+  "version": "1.0.0-beta.1",
+  "type": "module",
+  "description": "Spec-driven backend scaffolding: brownfield-scan gate, feature_id-keyed contracts, UUID bidirectional handles, stack-choice wiring.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/popixoxipop-collab/backend-skeleton.git"
+  },
+  "homepage": "https://github.com/popixoxipop-collab/backend-skeleton#readme",
+  "bugs": {
+    "url": "https://github.com/popixoxipop-collab/backend-skeleton/issues"
+  },
+  "bin": {
+    "bskel": "bin/bskel.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "contracts/",
+    "scanners/",
+    "handles/",
+    "new/",
+    "stack/",
+    "schemas/",
+    "scripts/preflight-base-ref.sh"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:pack": "node test/package-install.test.mjs",
+    "test:java-compile": "node scripts/java-compile-smoke.mjs",
+    "test:python-import": "node scripts/python-import-smoke.mjs",
+    "test:db-introspect": "node scripts/db-introspect-smoke.mjs",
+    "test:java-integration": "node scripts/java-integration-smoke.mjs",
+    "test:java-ast": "node scripts/java-ast-smoke.mjs",
+    "test:python-integration": "node scripts/python-integration-smoke.mjs",
+    "test:typescript-compile": "node scripts/typescript-typecheck-smoke.mjs",
+    "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.9.0",
+    "pg": "^8.23.0"
+  }
+}

package/scanners/adapters/_express-shared.mjs

@@ -0,0 +1,238 @@
+// G6 (D-javascript-express-adapter): the primitives `typescript-express.mjs` (G5) and
+// `javascript-express.mjs` (G6) genuinely share, extracted verbatim from the former when the
+// latter was written -- same `_`-prefixed shared-helper convention `_java-spring-analyzer.mjs`
+// already uses (scanners/registry.mjs skips `_`-prefixed files, so this file is never mistaken for
+// an adapter), and the same "three adapters had privately duplicated it" reasoning that produced
+// `scanners/text-util.mjs` under D-scanner-evidence.
+//
+// Deliberately NARROW: only the pieces that are byte-identical between the two adapters live here.
+// Endpoint extraction, mount-edge building and prefix resolution are NOT shared -- they diverge
+// materially (the TS adapter keys on a hardcoded `router` identifier and one node per FILE; the JS
+// adapter binds the real declared variable name and needs one node per (file, variable) pair, see
+// D-javascript-express-adapter). Parameterizing them into one function would have produced a worse
+// abstraction than two clear implementations, the same "narrow, not general" call this codebase
+// makes at every other cross-file resolution.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const EXCLUDE_GLOBS = ['!**/node_modules/**', '!**/dist/**', '!**/build/**'];
+export const VERBS = ['get', 'post', 'put', 'patch', 'delete'];
+
+// A string literal in any of the three forms real Express route registration actually uses --
+// found live in G5's own oracle: `router.use(\`/v1\`, v1)` uses a backtick TEMPLATE literal for a
+// plain path with no interpolation, not a regular string.
+export const STRING_LITERAL_RE = /^\s*["'`]([^"'`]*)["'`]/;
+
+export function listRgFiles(dir, globs) {
+	try {
+		const out = execFileSync('rg', ['--files', ...globs.flatMap((g) => ['-g', g]), ...EXCLUDE_GLOBS.flatMap((g) => ['-g', g]), dir], { encoding: 'utf8' });
+		return out.split('\n').filter(Boolean).sort(); // O6: rg --files order isn't guaranteed.
+	} catch {
+		return []; // rg exits 1 on "no files matched" -- not an error, just nothing to report
+	}
+}
+
+// `rg -l -e <pattern> -g <glob>...` -- the "which source files even mention this" pass both
+// adapters' detect() runs before doing any real reading.
+export function rgFilesMatching(pattern, globs, dir) {
+	try {
+		return execFileSync('rg', [
+			'-l', '-e', pattern,
+			...globs.flatMap((g) => ['-g', g]), ...EXCLUDE_GLOBS.flatMap((g) => ['-g', g]),
+			dir,
+		], { encoding: 'utf8' }).split('\n').filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+export function byShallowestThenName(a, b) {
+	const depthA = a.split(path.sep).length;
+	const depthB = b.split(path.sep).length;
+	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
+}
+
+export function listCandidatePackageFiles(repoRoot) {
+	return listRgFiles(repoRoot, ['package.json']).sort(byShallowestThenName);
+}
+
+// Real JSON.parse, not a bounded regex -- package.json is always valid JSON, so unlike
+// java-spring's build.gradle or python-fastapi's pyproject.toml (both need a "good-enough regex,
+// not a real parser" compromise), there is no regex-vs-parser trade-off to make here at all.
+export function readPackageJson(packageJsonPath) {
+	try {
+		return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+	} catch {
+		return null;
+	}
+}
+
+export function declaresExpress(packageJsonPath) {
+	const pkg = readPackageJson(packageJsonPath);
+	return Boolean(pkg?.dependencies?.express || pkg?.devDependencies?.express);
+}
+
+// G6: the JavaScript/TypeScript counterpart of `_java-spring-analyzer.mjs`'s `maskNonCode()`
+// (A2 Phase 1, D-java-analyzer), added for the same reason and against the same failure: a regex
+// scanning raw source cannot tell code from prose about code. Found live, not anticipated -- the
+// javascript-express fixture's own header comment contains the words `import { Router } from
+// 'express'` (describing what the TS adapter looks for), and an unmasked
+// `import\s+([^;]*?)\s*from\s*['"]express['"]` happily matched starting at the word "import"
+// INSIDE that comment and ran across the newline into the real statement below it, yielding a
+// nonsense import clause and silently collapsing the entire mount graph to empty prefixes.
+// The same exposure lets a commented-out `// router.get('/old', oldHandler)` be reported as a
+// live route by ANY of these regex adapters.
+//
+// Comments (line and block) are blanked to spaces ENTIRELY, markers included -- they must never
+// look structurally like anything. String and template literals are left FULLY INTACT, unlike the
+// Java masker which blanks string interiors: every path this adapter reports is read straight out
+// of a string literal (`router.get('/:id', ...)`), so blanking interiors would destroy the values
+// rather than protect them. Newlines are preserved and no character index shifts, so
+// `lineNumberAt()` and every `matchBalancedParens()` offset stay valid against the masked text.
+//
+// Regex literals ARE tracked, and not defensively: `const re = /'/g;` contains an odd number of
+// quote characters, and without regex tracking the scanner enters a phantom string that runs to
+// the next quote ANYWHERE later in the file -- leaving every comment in between unmasked, which is
+// precisely the phantom-route bug this function exists to prevent. Confirmed live before the
+// tracking was added. Whether `/` opens a regex or is division is decided from the previous
+// significant character (the standard JavaScript-lexer heuristic), and an unterminated literal
+// bails at end of line so a misjudged division can never run away past it.
+// Deliberately narrow. Arithmetic operators (`+ - * % ^ < > ~`) are legal regex-preceders in the
+// grammar but never appear before one in real code (`a + /re/` is a type error), while
+// `y++ / 2` IS real -- so including them buys nothing and costs a false positive. These twelve
+// cover every position a regex literal actually occupies in practice.
+const REGEX_PRECEDING_CHARS = new Set(['(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';']);
+const REGEX_PRECEDING_KEYWORD_RE = /\b(?:return|typeof|case|in|of|new|delete|do|else|yield|await|void|instanceof)\s*$/;
+
+function isRegexStart(lastSignificant, recentText) {
+	if (lastSignificant === null) return true; // start of file
+	if (REGEX_PRECEDING_CHARS.has(lastSignificant)) return true;
+	return REGEX_PRECEDING_KEYWORD_RE.test(recentText);
+}
+
+// Returns the index just past the literal's closing `/`. Handles `\` escapes and `[...]` character
+// classes (a `/` inside a class is not a terminator). Bails at a newline: a real regex literal
+// cannot span lines, so hitting one means this `/` was division after all, and stopping there
+// bounds the damage of a misjudgement to the rest of one line.
+function skipRegexLiteral(text, start) {
+	let i = start + 1;
+	let inClass = false;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === '\\') { i += 2; continue; }
+		if (ch === '\n') return i;
+		if (inClass) {
+			if (ch === ']') inClass = false;
+			i++;
+			continue;
+		}
+		if (ch === '[') { inClass = true; i++; continue; }
+		if (ch === '/') return i + 1;
+		i++;
+	}
+	return i;
+}
+
+export function maskJsComments(text) {
+	const out = text.split('');
+	let i = 0;
+	let quote = null; // "'" | '"' | '`' when inside a string/template literal
+	let lastSignificant = null; // last non-whitespace CODE character seen
+	while (i < text.length) {
+		const ch = text[i];
+		if (quote) {
+			if (ch === '\\') { i += 2; continue; }
+			if (ch === quote) { quote = null; lastSignificant = ch; }
+			i++;
+			continue;
+		}
+		if (ch === '\'' || ch === '"' || ch === '`') { quote = ch; i++; continue; }
+		// Comment markers win over regex detection unconditionally, and correctly: `//` is never a
+		// valid empty regex, and a regex body cannot begin with `*`.
+		if (ch === '/' && text[i + 1] === '/') {
+			while (i < text.length && text[i] !== '\n') { out[i] = ' '; i++; }
+			continue;
+		}
+		if (ch === '/' && text[i + 1] === '*') {
+			const end = text.indexOf('*/', i + 2);
+			const stop = end === -1 ? text.length : end + 2;
+			for (; i < stop; i++) if (text[i] !== '\n') out[i] = ' ';
+			continue;
+		}
+		if (ch === '/' && isRegexStart(lastSignificant, text.slice(Math.max(0, i - 12), i))) {
+			i = skipRegexLiteral(text, i);
+			lastSignificant = '/';
+			continue;
+		}
+		if (!/\s/.test(ch)) lastSignificant = ch;
+		i++;
+	}
+	return out.join('');
+}
+
+// Walks forward from `openIndex` (text[openIndex] must be '(') tracking paren depth -- needed
+// because a middleware array routinely nests its own parens/brackets, confirmed in G5's real
+// oracle: `router.get('/:id([0-9]+)', [checkJwt, checkRole(['ADMINISTRATOR'], true)], show)`.
+// Same technique python-fastapi.mjs's own matchBalancedParens already uses.
+export function matchBalancedParens(text, openIndex) {
+	let depth = 0;
+	for (let i = openIndex; i < text.length; i++) {
+		if (text[i] === '(') depth++;
+		else if (text[i] === ')') {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+
+// Splits a balanced top-level argument list on commas, respecting nested (), [], {} -- needed to
+// pull the LAST positional argument (the handler) out of `path, [middlewares], handler` without a
+// naive split(',') breaking on the commas inside `[checkJwt, checkRole(...)]`.
+export function splitTopLevelArgs(argsText) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < argsText.length; i++) {
+		const ch = argsText[i];
+		if ('([{'.includes(ch)) depth++;
+		else if (')]}'.includes(ch)) depth--;
+		else if (ch === ',' && depth === 0) {
+			parts.push(argsText.slice(start, i));
+			start = i + 1;
+		}
+	}
+	const last = argsText.slice(start);
+	if (last.trim() !== '') parts.push(last);
+	return parts.map((p) => p.trim());
+}
+
+export function joinPath(base, segment) {
+	const b = (base || '').replace(/\/$/, '');
+	const s = (segment || '').replace(/^\//, '');
+	return s ? `${b}/${s}` : (b || '/');
+}
+
+// Shared `diagnostics()` body for both Express adapters: whether any package.json was found at
+// all, whether any declares express, and whether `rg` (which both adapters shell out to, and which
+// they THROW on rather than degrade without) is actually on PATH.
+export function expressDiagnostics(repoRoot) {
+	const messages = [];
+	const pkgFiles = listCandidatePackageFiles(repoRoot);
+	if (pkgFiles.length === 0) {
+		messages.push({ level: 'info', code: 'no-package-json', message: 'no package.json found' });
+	} else if (!pkgFiles.some((f) => declaresExpress(f))) {
+		messages.push({ level: 'info', code: 'express-not-a-dependency', message: `found ${pkgFiles.length} package.json file(s), but none declare an express dependency` });
+	}
+	let rgOk = true;
+	try {
+		execFileSync('rg', ['--version'], { stdio: 'pipe' });
+	} catch {
+		rgOk = false;
+	}
+	if (!rgOk) {
+		messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it and will throw, not degrade, if it is missing' });
+	}
+	return messages;
+}