backend-skeleton 1.0.0-beta.1

package/handles/registry.mjs

@@ -0,0 +1,90 @@
+// G4: zero-registration codegen provider discovery -- mirrors scanners/registry.mjs's exact
+// mechanism (D-adapter-registry, G1), with one deliberate difference: a provider is selected by
+// EXACT id match against scanReport.adapter (bin/bskel.mjs), never arbitrated by specificity --
+// there is nothing to arbitrate since selection is 1:1, not "which of these best matches this
+// repo". See D-handles-providers in DECISIONS.md.
+//
+// SECURITY: `loadProviders({providersDir})` below is a test seam ONLY -- same rule as scanners/
+// registry.mjs's loadAdapters, never wire it to a CLI flag or environment variable.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const REGISTRY_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROVIDERS_DIR = path.join(REGISTRY_DIR, 'providers');
+const SCHEMAS_ROOT = path.join(REGISTRY_DIR, '..', 'schemas');
+const SUPPORTED_CONTRACT = 'sbf.handles-provider/1';
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) _ajv = new Ajv2020({ allErrors: true, strict: false });
+	return _ajv;
+}
+
+function loadProviderSchema() {
+	return JSON.parse(fs.readFileSync(path.join(SCHEMAS_ROOT, 'handles-provider.schema.json'), 'utf8'));
+}
+
+// Filenames only -- `providers/<id>/` implementation directories don't end in .mjs so they're
+// naturally excluded, no special-casing needed. Same O6-style determinism (.sort()) and `_`/`.`
+// skip convention as scanners/registry.mjs's candidateFiles.
+function candidateFiles(dir) {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((name) => name.endsWith('.mjs') && !name.startsWith('_') && !name.startsWith('.'))
+		.sort()
+		.map((name) => path.join(dir, name));
+}
+
+async function loadOneProvider(file, schema) {
+	const id = path.basename(file, '.mjs');
+	let mod;
+	try {
+		mod = await import(pathToFileURL(file).href);
+	} catch (err) {
+		return { error: { file, message: `failed to load: ${err.message}` } };
+	}
+	const descriptor = mod.provider;
+	if (!descriptor || typeof descriptor !== 'object') {
+		return { error: { file, message: 'must `export const provider = {...}` (sbf.handles-provider/1 shape) -- no such export found' } };
+	}
+	if (descriptor.contract !== SUPPORTED_CONTRACT) {
+		return { error: { file, message: `declares contract "${descriptor.contract}" -- this build only understands "${SUPPORTED_CONTRACT}"` } };
+	}
+	if (descriptor.id !== id) {
+		return { error: { file, message: `provider.id "${descriptor.id}" must equal its filename "${id}"` } };
+	}
+	const { plan, emit, ...jsonShape } = descriptor;
+	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	if (!validateFn(jsonShape)) {
+		const details = (validateFn.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
+		return { error: { file, message: `does not match schemas/handles-provider.schema.json: ${details}` } };
+	}
+	for (const fnName of ['plan', 'emit']) {
+		if (typeof descriptor[fnName] !== 'function') {
+			return { error: { file, message: `provider.${fnName} must be a function` } };
+		}
+	}
+	return { provider: descriptor };
+}
+
+export async function loadProviders({ providersDir = PROVIDERS_DIR } = {}) {
+	const schema = loadProviderSchema();
+	const providers = [];
+	const errors = [];
+	for (const file of candidateFiles(providersDir)) {
+		const result = await loadOneProvider(file, schema);
+		if (result.error) errors.push(result.error);
+		else providers.push(result.provider);
+	}
+	return { providers, errors };
+}
+
+export function providerById(providers, id) {
+	return providers.find((p) => p.id === id) ?? null;
+}
+
+// Top-level await -- see scanners/registry.mjs's identical note for why this is safe. bin/bskel.mjs's
+// cmdHandlesPlan/cmdHandlesEmit stay synchronous callers of PROVIDERS.
+export const { providers: PROVIDERS, errors: PROVIDER_LOAD_ERRORS } = await loadProviders();

package/lib/cli.mjs

@@ -0,0 +1,430 @@
+// D2 (D-cli-contract): strict argument parsing (node:util.parseArgs) + the JSON-diagnostic
+// channel every `bskel` command shares. This module is arg parsing + output glue only -- same
+// "CLI stays thin, real logic lives in lib/" split D1's lib/workflow.mjs and D5's lib/doctor.mjs
+// already established. See DECISIONS.md D-cli-contract for the full design and why the catalog's
+// own "every handler returns {ok,code,command,diagnostics,next_actions}" prescription was
+// rejected (it would break several commands' own schema-validated stdout artifacts).
+import { parseArgs } from 'node:util';
+import { REPO_GATE_ID } from './gate-definitions.mjs';
+
+export class CliUsageError extends Error {}
+
+const NUMERIC_RE = /^(0|[1-9]\d*)$/;
+
+function numericError(flag, def, got) {
+	const bounds = [
+		def.numeric.min != null ? `>= ${def.numeric.min}` : null,
+		def.numeric.max != null ? `<= ${def.numeric.max}` : null,
+	].filter(Boolean).join(' and ');
+	return `--${flag} must be a whole number${bounds ? ` ${bounds}` : ''} (got "${got}")`;
+}
+
+// D-cli-contract: mechanically transcribed from bin/bskel.mjs's pre-D2 `parseFlags(args, {...})`
+// call sites, one entry per command -- `options[flag].type`/`.default` are byte-identical to the
+// old spec. New fields this item adds: `numeric` (string-preserving min/max validation -- no
+// forced Number() coercion, so existing parseInt()/shell-arg-passing call sites need no changes),
+// `required` (existence-only; on failure this ALWAYS prints the command's own `usage` line, which
+// is exactly what every pre-D2 required-flag check already did -- see the grounding audit in
+// DECISIONS.md), `hidden` (kept out of --help and the usage()<->COMMANDS drift test -- unused as
+// of A4, which gave `scan`'s own `--db` a real implementation and its own usage() documentation).
+export const COMMANDS = {
+	preflight: {
+		usage: 'bskel preflight [--max-behind N] [--offline|--no-fetch] [--allow-dirty] [--max-age-minutes N] [--fetch-timeout-seconds N] [--json]',
+		options: {
+			'max-behind': { type: 'string', default: '0', numeric: { min: 0 } },
+			// D-preflight-freshness (S3): --offline is the real name; --no-fetch is kept as an
+			// exact alias (see scripts/preflight-base-ref.sh's own comment for why it isn't
+			// removed). Both declared here so neither is rejected as unknown.
+			offline: { type: 'boolean', default: false },
+			'no-fetch': { type: 'boolean', default: false },
+			'allow-dirty': { type: 'boolean', default: false },
+			// D-preflight-freshness (S3): how long a passed preflight stays fresh before `gate
+			// require`/downstream commands treat it as stale purely due to age (see
+			// lib/gate-definitions.mjs's `freshness` declaration for the 30-minute default and its
+			// data-derived justification). 0 disables the TTL entirely.
+			'max-age-minutes': { type: 'string', default: '30', numeric: { min: 0 } },
+			'fetch-timeout-seconds': { type: 'string', default: '60', numeric: { min: 0 } },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'gate require': {
+		usage: 'bskel gate require <name> [--feature <id>]',
+		options: { feature: { type: 'string', default: REPO_GATE_ID } },
+		allowPositionals: true,
+	},
+	'gate force': {
+		usage: 'bskel gate force <name> --reason "..." [--feature <id>] [--max-age-minutes N]',
+		options: {
+			feature: { type: 'string', default: REPO_GATE_ID },
+			reason: { type: 'string', default: '' },
+			'max-age-minutes': { type: 'string', default: null },
+		},
+		allowPositionals: true,
+	},
+	'gate revoke': {
+		usage: 'bskel gate revoke <name> --reason "..." [--feature <id>]',
+		options: {
+			feature: { type: 'string', default: REPO_GATE_ID },
+			reason: { type: 'string', default: '' },
+		},
+		allowPositionals: true,
+	},
+	'gate history': {
+		usage: 'bskel gate history <name> [--feature <id>] [--json]',
+		options: {
+			feature: { type: 'string', default: REPO_GATE_ID },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'gate show': {
+		usage: 'bskel gate show [<name>] [--feature <id>]',
+		options: { feature: { type: 'string', default: REPO_GATE_ID } },
+		allowPositionals: true,
+	},
+	scan: {
+		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]',
+		options: {
+			feature: { type: 'string', default: null },
+			terms: { type: 'string', default: '' },
+			// A4 (D-db-schema-plane): --db now does something real (Plane A migration-file scan,
+			// Plane C live introspection when --database-url-env is also given) -- no longer a
+			// documented-but-inert placeholder, so no longer `hidden`.
+			db: { type: 'boolean', default: false },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			json: { type: 'boolean', default: false },
+			'accept-low-confidence': { type: 'boolean', default: false },
+		},
+	},
+	'scan disposition': {
+		usage: 'bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			mode: { type: 'string', default: null },
+			// S2 (D-gate-precision, part 2): optional -- defaults to the same top-scored module
+			// contracts/emit.mjs's selectModule() would ALSO pick with no --module override, so an
+			// omitted flag here never silently disagrees with what `contract emit`/`handles plan`
+			// actually use by default.
+			module: { type: 'string', default: null },
+			note: { type: 'string', default: '' },
+			'breaking-approved': { type: 'boolean', default: false },
+		},
+	},
+	'scan explain': {
+		usage: 'bskel scan explain <module> --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'feature init': {
+		usage: 'bskel feature init --slug <name>',
+		options: { slug: { type: 'string', default: null, required: true } },
+	},
+	'feature list': {
+		usage: 'bskel feature list [--all] [--json]',
+		options: { all: { type: 'boolean', default: false }, json: { type: 'boolean', default: false } },
+	},
+	'feature show': {
+		usage: 'bskel feature show <id> [--json]',
+		options: { json: { type: 'boolean', default: false } },
+		allowPositionals: true,
+	},
+	'feature rename': {
+		usage: 'bskel feature rename <id> --to <new-slug> --reason "..." [--json]',
+		options: {
+			to: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'feature link': {
+		usage: 'bskel feature link <keepId> <aliasId> --reason "..." [--json]',
+		options: { reason: { type: 'string', default: '' }, json: { type: 'boolean', default: false } },
+		allowPositionals: true,
+	},
+	'feature archive': {
+		usage: 'bskel feature archive <id> --reason "..." [--json]',
+		options: { reason: { type: 'string', default: '' }, json: { type: 'boolean', default: false } },
+		allowPositionals: true,
+	},
+	'contract emit': {
+		usage: 'bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			module: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+			'openapi-file': { type: 'string', default: null },
+			'path-prefix': { type: 'string', default: null },
+		},
+	},
+	// A6 (D-openapi-export): the export direction. `--allow-unprefixed` is deliberately NOT a
+	// default-on convenience -- it overrides a refusal that exists because the scan found a global
+	// path-prefix signal the contract's own paths don't reflect, which is a wrong-paths-handed-to-a
+	// -client-generator risk, not a cosmetic one. `--status-codes` defaults to `range` (invents
+	// nothing); `literal` trades that for tooling compatibility, with a printed caveat.
+	'contract export': {
+		usage: 'bskel contract export --feature <id> [--out <path>] [--json] [--allow-unprefixed] [--status-codes range|literal]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			'allow-unprefixed': { type: 'boolean', default: false },
+			'status-codes': { type: 'string', default: 'range' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'contract waive': {
+		usage: 'bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path" | --all) --reason "..."',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			code: { type: 'string', default: null, required: true },
+			subject: { type: 'string', default: null },
+			all: { type: 'boolean', default: false },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'contract validate': {
+		usage: 'bskel contract validate --feature <id> --file <envelope.json>',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			file: { type: 'string', default: null, required: true },
+		},
+	},
+	'contract tool-schema': {
+		usage: 'bskel contract tool-schema --feature <id> --operation <operationId>',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			operation: { type: 'string', default: null, required: true },
+		},
+	},
+	'stack apply': {
+		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--json]',
+		options: {
+			choice: { type: 'string', default: null },
+			apply: { type: 'boolean', default: false },
+			port: { type: 'string', default: '8080', numeric: { min: 1, max: 65535 } },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'catalog lint': {
+		usage: 'bskel catalog lint [<choice>] [--json]',
+		options: { json: { type: 'boolean', default: false } },
+		allowPositionals: true,
+	},
+	'handles plan': {
+		usage: 'bskel handles plan --feature <id> [--module <name>] [--resource type1,type2] [--diff] [--ast]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			module: { type: 'string', default: null },
+			resource: { type: 'string', default: '' },
+			diff: { type: 'boolean', default: false },
+			// A2 Phase 2 (D-java-ast-helper): opt-in only -- runs the real JavaParser + Symbol
+			// Solver helper alongside the always-on regex classification and reports any
+			// disagreement. Never automatic; see ast-bridge.mjs.
+			ast: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'handles emit': {
+		usage: 'bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			module: { type: 'string', default: null },
+			resource: { type: 'string', default: '' },
+			force: { type: 'boolean', default: false },
+			reason: { type: 'string', default: '' },
+			check: { type: 'boolean', default: false },
+			diff: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// P2b (D-greenfield-parameters): every parameter below defaults to `null` rather than to its
+	// real default value, on purpose -- `cmdNew` has to distinguish "not passed" from "passed the
+	// same value the default happens to be" to (a) reject a Spring-only flag given with --stack
+	// fastapi and vice versa, and (b) avoid an extra network round-trip validating a --java-version
+	// nobody actually asked for. The real defaults live in new/spring.mjs / new/fastapi.mjs, one
+	// place each.
+	new: {
+		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none]',
+		options: {
+			stack: { type: 'string', default: null, required: true },
+			slug: { type: 'string', default: null, required: true },
+			dir: { type: 'string', default: null },
+			offline: { type: 'boolean', default: false },
+
+			// Both stacks.
+			name: { type: 'string', default: null },
+			description: { type: 'string', default: null },
+			// NOT `--version`: that is already a GLOBAL flag intercepted in main() before any
+			// command-specific parsing (it prints `bskel <version>`), so a command-level --version
+			// would be unreachable. This names the GENERATED project's own version field.
+			'project-version': { type: 'string', default: null },
+
+			// --stack spring only.
+			'group-id': { type: 'string', default: null },
+			'artifact-id': { type: 'string', default: null },
+			'package-name': { type: 'string', default: null },
+			'java-version': { type: 'string', default: null },
+			packaging: { type: 'string', default: null },
+			dependencies: { type: 'string', default: null },
+			'add-dependencies': { type: 'string', default: null },
+
+			// --stack fastapi only. `--port`'s numeric bounds mirror `stack apply --port` exactly
+			// (the default differs -- 8000 is uvicorn's, 8080 is Spring's -- but the VALIDATION shape
+			// is the one this CLI already declares for a port).
+			'python-version': { type: 'string', default: null },
+			port: { type: 'string', default: null, numeric: { min: 1, max: 65535 } },
+			license: { type: 'string', default: null },
+			database: { type: 'string', default: null },
+
+			// Declared-but-hidden: accepted by the parser purely so `cmdNew` can answer with the
+			// SPECIFIC reason each is refused (new/index.mjs's SPRING_REFUSED_PARAMS) instead of a
+			// bare "Unknown option". `hidden` keeps them out of --help and out of
+			// test/doc-integrity.test.mjs's usage()<->COMMANDS flag-set equality check.
+			type: { type: 'string', default: null, hidden: true },
+			language: { type: 'string', default: null, hidden: true },
+			'boot-version': { type: 'string', default: null, hidden: true },
+		},
+	},
+	'handles patch approve': {
+		usage: 'bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			module: { type: 'string', default: null },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			strategy: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	verify: {
+		usage: 'bskel verify --feature <id> [--build [--allow-skip-build]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			build: { type: 'boolean', default: false },
+			// S6 (D-verify-integrity): an explicit --build request must not silently no-op when no
+			// build tool is recognized -- this is the one opt-out, matching --force/--offline's own
+			// "explicit request needs an explicit escape hatch" shape elsewhere in this CLI.
+			'allow-skip-build': { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	status: {
+		usage: 'bskel status [--feature <id>] [--json]',
+		options: {
+			feature: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	next: {
+		usage: 'bskel next [--feature <id>] [--json]',
+		options: {
+			feature: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	doctor: {
+		usage: 'bskel doctor [--workflow scan|handles|stack] [--json]',
+		options: {
+			workflow: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+};
+
+function describeParseArgsError(err, spec) {
+	const known = [
+		...Object.keys(spec.options).filter((f) => !spec.options[f].hidden),
+		'help', 'json', 'quiet',
+	].sort().map((f) => `--${f}`).join(', ');
+	return `${err.message}\nusage: ${spec.usage}\nknown flags: ${known}`;
+}
+
+// Returns the SAME shape `parseFlags()` (pre-D2) returned: `{ _: [...positionals], ...values }`
+// -- every existing `flags.feature`/`flags._[0]`/`flags['max-behind']` call site in bin/bskel.mjs
+// needed zero changes for this. `flags.help === true` short-circuits BEFORE required-field
+// validation (so `bskel handles emit --help` renders help instead of failing on missing
+// --feature). Throws CliUsageError -- never calls process.exit itself, so this stays unit-testable
+// without spawning a process (see test/cli-contract.test.mjs).
+export function parseCommand(name, argv) {
+	const spec = COMMANDS[name];
+	if (!spec) throw new Error(`bskel-internal: no COMMANDS entry for "${name}"`);
+
+	const parseArgsOptions = { help: { type: 'boolean' }, quiet: { type: 'boolean' } };
+	for (const [flag, def] of Object.entries(spec.options)) parseArgsOptions[flag] = { type: def.type };
+	parseArgsOptions.json ??= { type: 'boolean' };
+
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options: parseArgsOptions,
+			strict: true,
+			allowPositionals: Boolean(spec.allowPositionals),
+		});
+	} catch (err) {
+		throw new CliUsageError(describeParseArgsError(err, spec));
+	}
+
+	const out = { _: parsed.positionals ?? [] };
+	for (const [flag, def] of Object.entries(spec.options)) {
+		out[flag] = Object.hasOwn(parsed.values, flag) ? parsed.values[flag] : def.default;
+	}
+	out.json = parsed.values.json ?? false;
+	out.quiet = Boolean(parsed.values.quiet);
+	out.help = Boolean(parsed.values.help);
+
+	for (const [flag, def] of Object.entries(spec.options)) {
+		if (!def.numeric || out[flag] == null) continue;
+		const value = out[flag];
+		if (!NUMERIC_RE.test(value) || (def.numeric.min != null && Number(value) < def.numeric.min) || (def.numeric.max != null && Number(value) > def.numeric.max)) {
+			throw new CliUsageError(numericError(flag, def, value));
+		}
+	}
+
+	if (out.help) return out;
+
+	for (const [flag, def] of Object.entries(spec.options)) {
+		if (def.required && !out[flag]) throw new CliUsageError(`usage: ${spec.usage}`);
+	}
+
+	return out;
+}
+
+export function renderCommandHelp(name) {
+	const spec = COMMANDS[name];
+	const lines = [`usage: ${spec.usage}`, '', 'flags:'];
+	for (const [flag, def] of Object.entries(spec.options)) {
+		if (def.hidden) continue;
+		const parts = [def.type];
+		if (def.default != null && def.type !== 'boolean') parts.push(`default: ${def.default}`);
+		if (def.required) parts.push('required');
+		lines.push(`  --${flag}  (${parts.join(', ')})`);
+	}
+	lines.push('  --json  (boolean)');
+	lines.push('  --quiet  (boolean)');
+	lines.push('  --help  (boolean)');
+	lines.push('', "see 'bskel --help' for the full command list");
+	return `${lines.join('\n')}\n`;
+}
+
+// D-cli-contract: the additive JSON diagnostic -- only ever printed on a PAYLOAD-LESS early-exit
+// path (a command that would otherwise have exited with empty stdout). Commands whose stdout is
+// itself a schema-validated artifact (scan/contract emit/handles plan, etc.) never call this --
+// see DECISIONS.md for why wrapping those would break `bskel scan --json > brownfield-scan.json`.
+export function diagnostic({ command, code, reason, message, next_actions = [] }) {
+	return {
+		schema: 'sbf.cli-diagnostic/1',
+		ok: false,
+		command,
+		code,
+		reason,
+		diagnostics: [{ level: 'error', reason, message }],
+		next_actions,
+	};
+}