backend-skeleton 1.0.0-beta.1

package/lib/workflow.mjs

@@ -0,0 +1,142 @@
+// D1: turns raw gate state into "what's blocking, what do I run next" -- `bskel verify` already
+// computes everything this needs (per-gate blocking/status/stale_reason/changed_inputs via
+// lib/verify.mjs's collectGateStatuses, missing artifacts via checkArtifacts), it just flattens
+// all of that into one pass/fail verdict instead of answering "what's the next command". This
+// module is presentation/sequencing logic layered on those same primitives -- reused directly,
+// not re-derived.
+import fs from 'node:fs';
+import path from 'node:path';
+import { GATE_NAMES, GATE_DEFINITIONS, VERIFY_POLICY } from './gate-definitions.mjs';
+import { collectGateStatuses, checkArtifacts, isBlockingGateResult } from './verify.mjs';
+import { getGate } from './state.mjs';
+import { requireNamedGate } from './gates.mjs';
+
+// This repo's own known features -- .sbf/feature-index.json is keyed by feature_uid (not
+// feature_id) and only ever holds a single-element array per uid, so it's not a convenient
+// "list every feature_id" source. specs/<id>/feature.json (written once by `feature init`,
+// never rewritten) is simpler and authoritative for what IDs actually exist.
+export function listFeatures(root) {
+	const specsRoot = path.join(root, 'specs');
+	if (!fs.existsSync(specsRoot)) return [];
+	return fs.readdirSync(specsRoot)
+		.filter((name) => fs.existsSync(path.join(specsRoot, name, 'feature.json')))
+		.map((featureId) => JSON.parse(fs.readFileSync(path.join(specsRoot, featureId, 'feature.json'), 'utf8')))
+		.sort((a, b) => a.feature_id.localeCompare(b.feature_id));
+}
+
+// The command that first establishes each gate -- same phrasing as the existing inline "blocked:
+// ... -- run `bskel ...` first" messages in requirePreflightPassed/cmdContractEmit/cmdHandlesEmit,
+// kept here as the one place both those call sites and this module could eventually share (not
+// done in this slice -- see D-status-next's COST in DECISIONS.md).
+const ESTABLISH_COMMAND = {
+	preflight: () => 'bskel preflight',
+	scan: (id) => `bskel scan --feature ${id} --terms <a,b,c>`,
+	contract: (id) => `bskel contract emit --feature ${id}`,
+	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
+	stack: () => 'bskel stack apply --choice <id> --apply',
+};
+
+// awaiting_disposition needs a genuinely different remediation per gate, not a re-run --
+// cmdScanDisposition's own usage line and cmdHandlesEmit's awaiting_disposition hint
+// (bin/bskel.mjs) already say exactly this; duplicated here rather than exported+imported to
+// avoid pulling CLI-layer string-building into lib/ for two lines of text.
+function awaitingDispositionCommand(gateName, featureId) {
+	if (gateName === 'scan') {
+		return `bskel scan disposition --feature ${featureId} --mode reuse|extend|replace|parallel --note "..."`;
+	}
+	if (gateName === 'contract') {
+		return `bskel contract waive --feature ${featureId} --code <CODE> (--subject "..."|--all) --reason "..."   # or: bskel gate force contract --feature ${featureId} --reason "..." if intentional`;
+	}
+	return `bskel gate force ${gateName} --feature ${featureId} --reason "..."`;
+}
+
+// Whether a recommended command WRITES anything (gate state, generated files, applied files) as
+// opposed to being a pure read (bskel verify, bskel status, bskel next itself). Matched by the
+// command's own leading "bskel <verb...>" prefix so this can't silently drift from the actual
+// command names above.
+const MUTATING_PREFIXES = ['bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive', 'bskel gate force', 'bskel handles emit', 'bskel handles plan', 'bskel stack apply'];
+
+function action(command, reason) {
+	return { command, reason, mutating: MUTATING_PREFIXES.some((p) => command.startsWith(p)) };
+}
+
+// featureId === null means "repo scope only" -- feature-scoped gates (scan/contract/handles)
+// cannot be meaningfully evaluated without a feature_id, so only `preflight` is considered.
+export function computeWorkflowState(root, featureId) {
+	let gates;
+	if (featureId) {
+		gates = collectGateStatuses(root, featureId, { getGate, requireNamedGate });
+	} else {
+		// Same call requirePreflightPassed already makes -- preflight's recompute() ignores
+		// featureId entirely (it's repo-scoped), so `null` here is exactly correct, not a stand-in.
+		const result = requireNamedGate(root, 'preflight', null);
+		const def = GATE_DEFINITIONS.preflight;
+		gates = [{
+			gate: 'preflight', scope: def.scope, policy: def.verifyPolicy,
+			required: def.verifyPolicy === VERIFY_POLICY.REQUIRED,
+			blocking: isBlockingGateResult(def, result),
+			ran: getGate(root, '_repo', 'preflight') !== null,
+			...result,
+		}];
+	}
+
+	const blockedBy = gates.filter((g) => g.blocking).map((g) => g.gate);
+	const nextActions = [];
+
+	// featureId === null means `gates` only ever contains the preflight entry (see above) -- every
+	// other gate name is legitimately absent, not "not_run", so `!g` must fall through to the next
+	// gate name rather than being treated as blocking. This loop can therefore only ever produce an
+	// action from `preflight` when there's no featureId; the "what comes after preflight" case (no
+	// feature selected yet) is handled in the fallback block below, not in here.
+	for (const gateName of GATE_NAMES) {
+		const g = gates.find((x) => x.gate === gateName);
+		if (!g || !g.blocking) continue; // not_run on an optional (required-when-present) gate isn't blocking -- isBlockingGateResult already encodes that.
+		if (g.status === 'not_run') {
+			nextActions.push(action(ESTABLISH_COMMAND[gateName](featureId), `${gateName} gate has not run yet`));
+		} else if (g.status === 'awaiting_disposition') {
+			nextActions.push(action(awaitingDispositionCommand(gateName, featureId), `${gateName} gate is awaiting disposition`));
+		} else if (g.status === 'stale') {
+			// D-preflight-freshness (S3): ttl_expired carries age_seconds/max_age_seconds (see
+			// lib/gates.mjs's checkFreshness()) -- worth a word count here, since "stale (ttl_expired)"
+			// alone doesn't say whether the pass is 1 minute or 1 day past its limit.
+			const staleDetail = g.stale_reason === 'inputs_changed'
+				? `: ${g.changed_inputs.join(', ')}`
+				: g.stale_reason === 'ttl_expired'
+					? ` (ttl_expired, ${Math.round(g.age_seconds / 60)}m old > ${Math.round(g.max_age_seconds / 60)}m limit)`
+					: g.stale_reason ? ` (${g.stale_reason})` : '';
+			nextActions.push(action(ESTABLISH_COMMAND[gateName](featureId), `${gateName} gate is stale${staleDetail}`));
+		}
+		break; // GATE_NAMES order -- only the earliest blocking gate; `next` promises exactly one action.
+	}
+
+	if (nextActions.length === 0) {
+		if (featureId) {
+			// Every required gate passes -- verify is the natural next step. Optional gates
+			// (handles/stack) that never ran are surfaced separately, not as a blocking action.
+			nextActions.push(action(`bskel verify --feature ${featureId}`, 'all required gates pass -- verify the full feature state'));
+		} else {
+			// preflight passed and no --feature was given -- there is no gate to hook this off of
+			// (feature-scoped gates aren't even evaluated without a feature_id), so point at
+			// starting or selecting one directly.
+			const features = listFeatures(root);
+			if (features.length === 0) {
+				nextActions.push(action('bskel feature init --slug <name>', 'no feature exists yet -- create one to start the scan/contract/handles workflow'));
+			} else {
+				nextActions.push(action(
+					'bskel next --feature <id>',
+					`pick an existing feature to continue (known: ${features.map((f) => f.feature_id).join(', ')}), or run \`bskel feature init --slug <name>\` to start a new one`,
+				));
+			}
+		}
+	}
+
+	const optionalNotRun = gates.filter((g) => (g.gate === 'handles' || g.gate === 'stack') && g.status === 'not_run').map((g) => g.gate);
+
+	return {
+		gates,
+		artifacts: featureId ? checkArtifacts(root, featureId, gates) : [],
+		blocked_by: blockedBy,
+		next_actions: nextActions,
+		optional_not_run: optionalNotRun,
+	};
+}

package/new/fastapi.mjs

@@ -0,0 +1,165 @@
+// P2 (D-greenfield-bootstrap): unlike Spring, FastAPI has no first-party scaffolding CLI/service
+// with comparable official standing to Spring Initializr (confirmed while researching this item)
+// -- so "pinned starter" here means a minimal, LOCAL, hand-written template matching the exact
+// layout scanners/adapters/python-fastapi.mjs's own detectPythonFastApiRoot() already expects
+// (a pyproject.toml declaring a `fastapi` dependency + a .py file that imports/instantiates it),
+// not a third-party generator. No network call.
+//
+// P2b (D-greenfield-parameters): this is the half of `bskel new` with NO upstream authority at all
+// -- there is no Initializr here to bounce a bad value back, so every value this file writes is one
+// `bskel` itself is the last check on. Two consequences, both deliberate: the {{VAR}} renderer is
+// now the shared one (lib/template.mjs), and every rendered file is scanned for a SURVIVING {{VAR}}
+// before anything reaches disk -- a scaffold that would ship a literal `{{FOO}}` into a user's
+// pyproject.toml fails CLOSED instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderTemplateText, findResidualTemplateVars } from '../lib/template.mjs';
+
+const DEFAULT_TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'templates', 'fastapi');
+
+export const DEFAULT_PROJECT_VERSION = '0.1.0';
+export const DEFAULT_REQUIRES_PYTHON = '>=3.11';
+export const DEFAULT_PORT = '8000';
+export const DEFAULT_DATABASE = 'none';
+
+// P2b: the driver pin, and ONLY the driver pin. `--database` never generates engine/session wiring,
+// a db.py, or a models package -- that would be `bskel` inventing the user's domain, the same line
+// `D-resolver-scope` draws for patchField() and `D-javascript-express-adapter`'s Phase 2 draws for
+// generated SQL. sqlite needs no third-party driver at all (CPython ships sqlite3, and SQLModel/
+// SQLAlchemy drive it through the stdlib module), so it correctly adds nothing.
+const DATABASE_DEPENDENCIES = Object.freeze({
+	postgres: ['psycopg[binary]>=3.2'],
+	sqlite: [],
+	none: [],
+});
+
+// TOML basic strings and Python double-quoted strings share the two escapes that matter here.
+// Newlines/control characters are rejected upstream (new/params.mjs's requireSingleLineText), so a
+// backslash and a double quote are the whole surface.
+function escapeQuoted(value) {
+	return String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+
+function buildVars({ slug, name, description, projectVersion, requiresPython, port, license, database }) {
+	const resolvedName = name ?? slug;
+	const resolvedDatabase = database ?? DEFAULT_DATABASE;
+	const driverLines = (DATABASE_DEPENDENCIES[resolvedDatabase] ?? [])
+		.map((dep) => `    "${escapeQuoted(dep)}",\n`)
+		.join('');
+
+	const databaseSection = resolvedDatabase === 'none' ? '' : [
+		'## Database',
+		'',
+		resolvedDatabase === 'postgres'
+			? '`--database postgres` pinned `psycopg[binary]` in `pyproject.toml`. That is all it did.'
+			: '`--database sqlite` pinned no extra driver -- CPython ships `sqlite3`, which SQLModel/SQLAlchemy drive directly.',
+		'',
+		'No engine, session, or connection code was generated: the connection URL, pooling, migrations',
+		'and session lifecycle are decisions about your application, not ones a scaffolder should make',
+		'for you. Wire them up yourself before adding models.',
+		'',
+		'',
+	].join('\n');
+
+	return {
+		SLUG: slug,
+		NAME: escapeQuoted(resolvedName),
+		DESCRIPTION: escapeQuoted(description ?? ''),
+		PROJECT_VERSION: escapeQuoted(projectVersion ?? DEFAULT_PROJECT_VERSION),
+		REQUIRES_PYTHON: escapeQuoted(requiresPython ?? DEFAULT_REQUIRES_PYTHON),
+		// A whole line, including its trailing newline, so an absent --license leaves no blank line
+		// behind. There is no neutral default SPDX identifier -- emitting one would be this tool
+		// asserting a legal claim the user never made -- so the key is omitted entirely instead.
+		LICENSE_LINE: license == null ? '' : `license = "${escapeQuoted(license)}"\n`,
+		DATABASE_DEPENDENCY_LINES: driverLines,
+		DESCRIPTION_BLOCK: description ? `${description}\n\n` : '',
+		PORT: String(port ?? DEFAULT_PORT),
+		DATABASE_SECTION: databaseSection,
+	};
+}
+
+// Renders the whole tree into memory FIRST, so the residual-variable check below can fail before a
+// single byte reaches disk. Deliberately not "write, then verify, then delete": `dir` comes from
+// user input (`--dir`), and an rm -rf of a user-supplied path to clean up after our own bug is a
+// worse failure mode than the bug. Nothing partial ever exists.
+function renderTree(srcDir, destDir, vars) {
+	const files = [];
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		const srcPath = path.join(srcDir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...renderTree(srcPath, path.join(destDir, entry.name), vars));
+			continue;
+		}
+		// The template's own gitignore is named without a leading dot (see new/templates/fastapi/
+		// gitignore) so this repo's own tooling never treats it as a real, active .gitignore.
+		const destName = entry.name === 'gitignore' ? '.gitignore' : entry.name;
+		files.push({
+			destPath: path.join(destDir, destName),
+			content: renderTemplateText(fs.readFileSync(srcPath, 'utf8'), vars),
+		});
+	}
+	return files;
+}
+
+export async function scaffoldFastapi({
+	dir,
+	slug,
+	name = null,
+	description = null,
+	projectVersion = null,
+	requiresPython = null,
+	port = null,
+	license = null,
+	database = null,
+	// Internal test seam only -- never wired to a CLI flag. `test/new-cli.test.mjs` points this at a
+	// deliberately broken template to prove the fail-closed check below can actually fail.
+	templateDir = DEFAULT_TEMPLATE_DIR,
+} = {}) {
+	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 vars = buildVars({ slug, name, description, projectVersion, requiresPython, port, license, database });
+	const files = renderTree(templateDir, dir, vars);
+
+	// P2b: the fail-closed half. P4's `bskel catalog lint` has run this same check over
+	// stack/catalog/ templates since D-extension-conformance; new/templates/** never had it, so a
+	// template variable added without a matching entry in buildVars() above would have shipped a
+	// literal `{{FOO}}` into a real user's pyproject.toml with nothing to catch it.
+	const offenders = files
+		.map((f) => ({ rel: path.relative(dir, f.destPath), tokens: findResidualTemplateVars(f.content) }))
+		.filter((f) => f.tokens.length > 0);
+	if (offenders.length > 0) {
+		const detail = offenders.map((f) => `${f.rel}: ${f.tokens.join(', ')}`).join('; ');
+		throw new Error(`bskel-internal: the fastapi template left unsubstituted variable(s) after rendering (${detail}) -- refusing to write a project containing literal template tokens. Nothing was written.`);
+	}
+
+	for (const f of files) {
+		fs.mkdirSync(path.dirname(f.destPath), { recursive: true });
+		fs.writeFileSync(f.destPath, f.content);
+	}
+
+	const resolvedDatabase = database ?? DEFAULT_DATABASE;
+	const postScaffoldNotes = [];
+	if (resolvedDatabase !== 'none') {
+		// Accurate per choice: postgres really did add a dependency line, sqlite deliberately added
+		// nothing at all (CPython ships sqlite3). Saying "pinned the driver" for sqlite would be a
+		// small lie in exactly the place this note exists to prevent one.
+		const did = resolvedDatabase === 'postgres'
+			? 'pinned psycopg[binary] in pyproject.toml'
+			: 'pinned no extra dependency (CPython ships sqlite3, which SQLModel/SQLAlchemy drive directly)';
+		postScaffoldNotes.push(`--database ${resolvedDatabase} ${did}. That is all it did. NOT done automatically: the engine, session and connection-URL wiring, or any migration setup -- see the "Database" section of the generated README.md.`);
+	}
+
+	return {
+		dir,
+		name: name ?? slug,
+		projectVersion: projectVersion ?? DEFAULT_PROJECT_VERSION,
+		requiresPython: requiresPython ?? DEFAULT_REQUIRES_PYTHON,
+		port: String(port ?? DEFAULT_PORT),
+		license: license ?? null,
+		database: resolvedDatabase,
+		postScaffoldNotes,
+	};
+}

package/new/index.mjs

@@ -0,0 +1,62 @@
+// P2 (D-greenfield-bootstrap): a plain dispatch map, NOT scanners/registry.mjs's/handles/
+// registry.mjs's dynamic-load-and-validate machinery -- those exist for genuine THIRD-PARTY
+// extensibility (G1/G4's explicit design goal, a schema-validated contract other adapters/
+// providers can implement). `bskel new`'s two stacks are first-party-only with no such need; a
+// simple object map is the honest amount of structure for two fixed choices, not an
+// under-justified copy of a pattern built for a different problem.
+//
+// P2b (D-greenfield-parameters): the record shape is WIDER (each stack now declares which
+// parameters it accepts and which it explicitly refuses), and deliberately still a plain object.
+// The reason two first-party stacks don't justify a registry hasn't changed just because each entry
+// grew three fields.
+import { scaffoldSpring } from './spring.mjs';
+import { scaffoldFastapi } from './fastapi.mjs';
+
+// Parameters describing the generated project itself, meaningful to any stack.
+const COMMON_PARAMS = ['name', 'description', 'project-version'];
+
+// P2b: three Spring Initializr parameters this tool refuses OUTRIGHT rather than passing through --
+// each for a specific, cited reason about what would break downstream, not "not supported yet".
+// Declared here (rather than simply left undeclared) so a user who reasonably expects them -- they
+// are all real controls on start.spring.io's own web UI -- gets the reason instead of a bare
+// "unknown option". They are `hidden` in lib/cli.mjs's COMMANDS table, so they stay out of --help
+// and out of the usage()<->COMMANDS drift test, exactly the mechanism `scan --db` used while it was
+// a documented-but-inert placeholder.
+const SPRING_REFUSED_PARAMS = Object.freeze({
+	type: '--type is not supported: `bskel new --stack spring` always requests a Gradle-Groovy project. handles/providers/java-spring/emit.mjs\'s detectJacksonPackage() reads build.gradle ONLY and falls back to the Jackson 2 package when it is absent -- a Maven (pom.xml) or Kotlin-DSL (build.gradle.kts) scaffold would therefore make a later `bskel handles emit` generate code importing com.fasterxml.jackson.databind.ObjectMapper, which is not on the classpath under Initializr\'s current default Spring Boot 4 (Jackson 3). A project that scaffolds fine and then fails to compile is worse than a refusal.',
+	language: '--language is not supported: `bskel new --stack spring` always requests Java. scanners/adapters/java-spring.mjs\'s listJavaFiles() globs *.java only and detectJavaSpringRoot() requires src/main/java, and every handles/providers/java-spring template emits .java -- a Kotlin or Groovy scaffold would fall straight through to the generic-grep fallback adapter (specificity 0, confidence "low", no codegen provider at all).',
+	'boot-version': '--boot-version is not supported: start.spring.io answers an unknown bootVersion with HTTP 500 and an internal Spring config-class error, which is not something worth surfacing to you, and pinning an exact Boot version is a maintenance liability this tool already argued against (see D-greenfield-bootstrap -- Initializr only serves actively-supported versions and ages old ones out on its own schedule, and detectJacksonPackage() already adapts to whichever major version comes back).',
+});
+
+export const STACKS = Object.freeze({
+	spring: Object.freeze({
+		id: 'spring',
+		scaffold: scaffoldSpring,
+		requiresNetwork: true,
+		acceptedParams: Object.freeze([
+			...COMMON_PARAMS,
+			'group-id', 'artifact-id', 'package-name', 'java-version', 'packaging',
+			'dependencies', 'add-dependencies',
+		]),
+		refusedParams: SPRING_REFUSED_PARAMS,
+	}),
+	fastapi: Object.freeze({
+		id: 'fastapi',
+		scaffold: scaffoldFastapi,
+		requiresNetwork: false,
+		acceptedParams: Object.freeze([...COMMON_PARAMS, 'python-version', 'port', 'license', 'database']),
+		refusedParams: Object.freeze({}),
+	}),
+});
+
+// Every parameter any stack knows about -- the set cmdNew checks a passed flag against to decide
+// "wrong stack" vs. "not a stack parameter at all". Derived, never a hand-maintained third list.
+export const ALL_STACK_PARAMS = Object.freeze([...new Set(
+	Object.values(STACKS).flatMap((s) => [...s.acceptedParams, ...Object.keys(s.refusedParams)]),
+)]);
+
+// Which stack DOES accept a given parameter -- so a cross-stack rejection can name the right one
+// ("--group-id applies to --stack spring") instead of just saying no.
+export function stacksAccepting(param) {
+	return Object.values(STACKS).filter((s) => s.acceptedParams.includes(param)).map((s) => s.id);
+}

package/new/params.mjs

@@ -0,0 +1,233 @@
+// P2b (D-greenfield-parameters): local validation for the `bskel new` parameters where letting
+// Spring Initializr's own HTTP 400 be the check is NOT safe.
+//
+// The split is measured, not assumed (see the validation matrix in DECISIONS.md's
+// D-greenfield-parameters): `dependencies`/`type`/`packaging`/`language` all fail CLOSED at
+// start.spring.io with a clean, quotable 400 message, so those stay pass-through. `groupId`/
+// `packageName` fail OPEN -- `groupId=com.new` (a JLS reserved word as a package segment) and
+// `groupId=has space` both return HTTP 200 and a project that cannot compile -- so they need a real
+// local validator. `javaVersion` also fails OPEN (`javaVersion=99` returns 200 and writes
+// `JavaLanguageVersion.of(99)` straight into build.gradle), but its valid set is a MOVING external
+// fact, so it is checked against a live metadata fetch rather than a local list (see below).
+//
+// Why a local Java validator does not go stale the way a local dependency-id or javaVersion list
+// would: the Java package-name grammar (JLS 3.8) and the reserved-keyword list (JLS 3.9) are
+// language-specification constants, not a service's current catalog. Adding a keyword to Java is a
+// language-version event; adding a starter to Initializr happens continuously.
+import { SLUG_RE } from '../lib/featureid.mjs';
+
+// JLS 3.9, complete: the 50 classic reserved keywords plus `_` (a keyword since Java 9) -- 51 in
+// the current JLS 3.9 list -- plus the three
+// reserved literals (`true`/`false`/`null` -- not keywords per the spec, but equally illegal as an
+// identifier, which is the only property this validator cares about). Deliberately does NOT include
+// contextual keywords (`var`, `record`, `yield`, `sealed`, `permits`, `module`, ...) -- those remain
+// legal identifiers in general contexts, and rejecting them would be over-validation.
+export const JAVA_RESERVED_WORDS = new Set([
+	'abstract', 'assert', 'boolean', 'break', 'byte', 'case', 'catch', 'char', 'class', 'const',
+	'continue', 'default', 'do', 'double', 'else', 'enum', 'extends', 'final', 'finally', 'float',
+	'for', 'goto', 'if', 'implements', 'import', 'instanceof', 'int', 'interface', 'long', 'native',
+	'new', 'package', 'private', 'protected', 'public', 'return', 'short', 'static', 'strictfp',
+	'super', 'switch', 'synchronized', 'this', 'throw', 'throws', 'transient', 'try', 'void',
+	'volatile', 'while', '_',
+	'true', 'false', 'null',
+]);
+
+// ASCII only, on purpose. The Java language itself accepts any `Character.isJavaIdentifierStart`
+// codepoint (so `com.café` really is a legal package name), but this is a scaffolder writing a
+// directory tree that has to survive whatever filesystem, zip extractor and CI runner the project
+// later lands on -- and Initializr accepts a non-ASCII groupId with HTTP 200 either way, so nothing
+// upstream is checking it. Narrower than the language, deliberately, and documented as such.
+const JAVA_IDENTIFIER_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// A control character or a newline in a value that gets written into a TOML/Python/Gradle string
+// literal breaks the generated file rather than the request -- rejected before anything is written.
+function hasControlCharacters(value) {
+	for (const ch of value) {
+		const code = ch.codePointAt(0);
+		if (code < 0x20 || code === 0x7f) return true;
+	}
+	return false;
+}
+
+export function requireSingleLineText(value, flag) {
+	if (typeof value !== 'string') throw new Error(`--${flag} must be a string`);
+	if (hasControlCharacters(value)) {
+		throw new Error(`invalid --${flag} -- must not contain newlines or control characters (it is written verbatim into a generated file)`);
+	}
+	return value;
+}
+
+// Shared by --group-id and --package-name: same grammar, so one validator, per this project's own
+// "one implementation, two call sites" habit (lib/template.mjs, scanners/text-util.mjs).
+export function requireValidJavaPackageName(value, flag) {
+	if (typeof value !== 'string' || value === '') {
+		throw new Error(`invalid --${flag} "${value}" -- expected a dot-separated Java package name (e.g. com.example)`);
+	}
+	const segments = value.split('.');
+	for (const segment of segments) {
+		if (segment === '') {
+			throw new Error(`invalid --${flag} "${value}" -- empty package segment (a leading, trailing or doubled ".")`);
+		}
+		if (!JAVA_IDENTIFIER_SEGMENT_RE.test(segment)) {
+			throw new Error(`invalid --${flag} "${value}" -- segment "${segment}" is not a Java identifier (ASCII letters, digits and "_", never starting with a digit). start.spring.io accepts this with HTTP 200 and generates a project that will not compile, so it is checked here.`);
+		}
+		if (JAVA_RESERVED_WORDS.has(segment)) {
+			throw new Error(`invalid --${flag} "${value}" -- segment "${segment}" is a Java reserved word (JLS 3.9) and cannot be a package segment. start.spring.io accepts this with HTTP 200 and generates a project that will not compile, so it is checked here.`);
+		}
+	}
+	return value;
+}
+
+// Reuses lib/featureid.mjs's own SLUG_RE -- the exact validator `--slug` (whose value is what
+// `--artifact-id` defaults to) already passes through, rather than a second, subtly different
+// artifact-id grammar.
+export function requireValidArtifactId(value) {
+	if (typeof value !== 'string' || !SLUG_RE.test(value)) {
+		throw new Error(`invalid --artifact-id "${value}" -- expected lowercase-hyphenated words (e.g. my-service), the same shape --slug accepts`);
+	}
+	return value;
+}
+
+// ★ Found live, not reasoned about: the first working `bskel new --stack fastapi --name "Demo
+// Service"` run produced a pyproject.toml with `name = "Demo Service"`, which is valid TOML and an
+// INVALID project name -- `pip install -e .` rejects it outright. Unlike Spring, where Initializr
+// sanitizes `name` into a main-class identifier on its own, nothing downstream of this tool checks
+// a FastAPI project name at all. Same category as the Java package validator above: a fixed grammar
+// from a published specification (PEP 508 / the PyPA name spec, reproduced verbatim below), so a
+// local check here does not go stale the way a copy of a service's current catalog would.
+//
+// Consequence, documented rather than worked around: `--name` sets BOTH pyproject.toml's `name` and
+// FastAPI's `title=`, so a prose title with spaces is rejected. Editing `app/main.py`'s one
+// `FastAPI(title=...)` line afterwards is the escape hatch; splitting this into two flags would be
+// inventing a distinction the user did not ask for.
+const PYTHON_PROJECT_NAME_RE = /^([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9])$/;
+
+export function requireValidPythonProjectName(value) {
+	if (typeof value !== 'string' || !PYTHON_PROJECT_NAME_RE.test(value)) {
+		throw new Error(`invalid --name "${value}" -- must be a valid Python project name (PEP 508: ASCII letters, digits, ".", "-" and "_", starting and ending alphanumeric). It is written into pyproject.toml's [project] name, which pip validates -- a name with spaces produces a project that scaffolds fine and cannot be installed.`);
+	}
+	return value;
+}
+
+// `requires-python` is a PEP 440 version specifier. There is no live authority to check a Python
+// version against the way start.spring.io's metadata is one for Java (python.org publishes no
+// equivalent machine-readable "currently supported" document this tool could consult on demand),
+// and the value is only ever substituted into pyproject.toml as a string -- so this validates that
+// it is SYNTACTICALLY sane, never that the version exists.
+//
+// Accepted, deliberately narrow (one clause, no comma-joined specifier sets): a bare `3.12` /
+// `3.12.1` (normalized to `>=3.12`), or an explicit single-operator floor (`>=3.12`, `>3.12`,
+// `~=3.12`, `==3.12`). A bare upper bound (`<3.13`) is rejected because the flag is documented as a
+// FLOOR -- silently accepting a specifier that says the opposite of what the flag is named would be
+// the exact "the generated file encodes a claim the user did not state" failure this item's own
+// safe/unsafe line rules out. A project needing a compound specifier edits one line of the
+// generated pyproject.toml, which is a file it now owns outright.
+const PYTHON_VERSION_RE = /^(>=|>|~=|==)?(\d+)\.(\d+)(?:\.(\d+))?$/;
+
+// The shipped FastAPI template's own floor, not a claim about Python or FastAPI in general:
+// new/templates/fastapi/app/main.py annotates `-> dict[str, str]`, a PEP 585 builtin generic that
+// raises TypeError at runtime before 3.9, and FastAPI evaluates route return annotations.
+export const FASTAPI_TEMPLATE_MIN_PYTHON = { major: 3, minor: 9 };
+
+export function parsePythonVersion(value) {
+	if (typeof value !== 'string') return null;
+	const m = PYTHON_VERSION_RE.exec(value.trim());
+	if (!m) return null;
+	return {
+		operator: m[1] ?? '>=',
+		major: Number(m[2]),
+		minor: Number(m[3]),
+		patch: m[4] == null ? null : Number(m[4]),
+		release: m[4] == null ? `${m[2]}.${m[3]}` : `${m[2]}.${m[3]}.${m[4]}`,
+	};
+}
+
+// Returns `{ requiresPython, warnings }` -- the exact string to substitute into pyproject.toml's
+// `requires-python`, plus any "this is legal but your generated code needs more" notes. Warns
+// rather than refuses, matching --dependencies' own "warn loudly, then trust the user" register:
+// a caller who intends to rewrite app/main.py is making a legitimate choice this tool should not
+// veto.
+export function requireValidPythonVersion(value) {
+	const parsed = parsePythonVersion(value);
+	if (!parsed) {
+		throw new Error(`invalid --python-version "${value}" -- expected a bare version (3.12, 3.12.1) or a single-operator floor (>=3.12, >3.12, ~=3.12, ==3.12); a compound specifier or a bare upper bound is not accepted (this flag sets pyproject.toml's requires-python FLOOR)`);
+	}
+	const warnings = [];
+	const belowTemplateFloor = parsed.major < FASTAPI_TEMPLATE_MIN_PYTHON.major
+		|| (parsed.major === FASTAPI_TEMPLATE_MIN_PYTHON.major && parsed.minor < FASTAPI_TEMPLATE_MIN_PYTHON.minor);
+	if (belowTemplateFloor) {
+		warnings.push(`--python-version ${value} sets requires-python below ${FASTAPI_TEMPLATE_MIN_PYTHON.major}.${FASTAPI_TEMPLATE_MIN_PYTHON.minor}, which the generated app/main.py itself needs: its \`-> dict[str, str]\` return annotation is a PEP 585 builtin generic that raises TypeError at runtime on older interpreters, and FastAPI evaluates route return annotations. Scaffolding anyway -- rewrite app/main.py's annotations if you really mean to target ${parsed.release}.`);
+	}
+	return { requiresPython: `${parsed.operator}${parsed.release}`, warnings };
+}
+
+// An SPDX identifier or short expression. Deliberately NOT checked against a bundled copy of the
+// SPDX license list: that list is external truth that changes, and a stale local copy of external
+// truth is the exact thing this project refuses everywhere else (D-greenfield-bootstrap's rejected
+// `.bskel/config.yml`, `runScan()`'s fresh-every-run adapter detection). Unlike --java-version there
+// is no cheap on-demand authority to consult either, so this validates SHAPE only -- enough to keep
+// the value from breaking the TOML string it lands in.
+const LICENSE_RE = /^[A-Za-z0-9][A-Za-z0-9.+ ()-]*$/;
+
+export function requireValidLicense(value) {
+	if (typeof value !== 'string' || !LICENSE_RE.test(value)) {
+		throw new Error(`invalid --license "${value}" -- expected an SPDX identifier or short expression (e.g. MIT, Apache-2.0, "MIT OR Apache-2.0"). Not checked against the real SPDX list -- this tool keeps no local copy of external truth.`);
+	}
+	return value;
+}
+
+export const DATABASE_CHOICES = Object.freeze(['postgres', 'sqlite', 'none']);
+
+export function requireValidDatabase(value) {
+	if (!DATABASE_CHOICES.includes(value)) {
+		throw new Error(`invalid --database "${value}" -- expected one of: ${DATABASE_CHOICES.join(', ')}`);
+	}
+	return value;
+}
+
+// ---- --java-version: on-demand live metadata, never cached, never persisted ----------------
+//
+// start.spring.io/metadata/client is the same document the start.spring.io web UI populates its own
+// dropdowns from. Fetched ONLY when a non-default --java-version is actually passed (a user who
+// doesn't ask pays no extra network call), and never written to disk -- consistent with
+// D-greenfield-bootstrap's refusal to persist a `.bskel/config.yml`, and with the whole project's
+// position that a local copy of a moving external fact is worse than no copy.
+export const INITIALIZR_METADATA_URL = 'https://start.spring.io/metadata/client';
+
+// Measured 2026-08-23: `javaVersion` is `{type, default, values: [{id, name}, ...]}` with ids
+// ["26","25","21","17"] and default "17". Parsed defensively anyway -- a shape change upstream must
+// produce a clean, actionable message here, not a TypeError.
+export async function fetchSupportedJavaVersions({ fetchImpl = globalThis.fetch } = {}) {
+	let response;
+	try {
+		response = await fetchImpl(INITIALIZR_METADATA_URL, { headers: { Accept: 'application/json' } });
+	} catch (err) {
+		throw new Error(`could not reach start.spring.io to validate --java-version (${err.message}) -- check network access, or omit --java-version to use this tool's own default`);
+	}
+	if (!response.ok) {
+		throw new Error(`start.spring.io returned ${response.status} ${response.statusText} for its own version metadata -- the request was: ${INITIALIZR_METADATA_URL}`);
+	}
+	let body;
+	try {
+		body = await response.json();
+	} catch (err) {
+		throw new Error(`start.spring.io's version metadata was not readable JSON (${err.message}) -- the request was: ${INITIALIZR_METADATA_URL}`);
+	}
+	const values = body?.javaVersion?.values;
+	const ids = Array.isArray(values) ? values.map((v) => v?.id).filter((id) => typeof id === 'string' && id !== '') : [];
+	if (ids.length === 0) {
+		throw new Error(`start.spring.io's version metadata carried no javaVersion.values list -- cannot validate --java-version against it. The request was: ${INITIALIZR_METADATA_URL}`);
+	}
+	return ids;
+}
+
+export async function requireSupportedJavaVersion(javaVersion, opts = {}) {
+	if (typeof javaVersion !== 'string' || javaVersion === '') {
+		throw new Error(`invalid --java-version "${javaVersion}" -- expected a version id start.spring.io offers (e.g. 17, 21, 25)`);
+	}
+	const supported = await fetchSupportedJavaVersions(opts);
+	if (!supported.includes(javaVersion)) {
+		throw new Error(`--java-version ${javaVersion} is not one start.spring.io currently offers (it offers: ${supported.join(', ')}). This is checked here because start.spring.io accepts an unknown javaVersion with HTTP 200 and writes it straight into build.gradle as JavaLanguageVersion.of(${javaVersion}) -- a project that downloads fine and never compiles.`);
+	}
+	return javaVersion;
+}