kalup 0.1.0

package/dist/host-BJWvo3sX.mjs

@@ -0,0 +1,390 @@
+import { A as sanitize, C as usageError, D as disclaimer, E as bin, O as escapeJson, S as versionText, T as KalupError, b as formats, k as exitCodes, u as KalupCommand, w as IssueError, x as version, y as PATH_MAX } from "./commands-C--Xsk1p.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Config, Errors, Help } from "@oclif/core";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+//#region src/lib/output.ts
+/** Builds an envelope/1 document. `data` is left out when undefined. */
+function envelope(ok, data, issues = []) {
+	return {
+		format: "envelope/1",
+		ok,
+		...data === void 0 ? {} : { data },
+		issues
+	};
+}
+/** Prints one envelope/1 document, the only thing `--json` writes to stdout. Keys stay in envelope order. */
+function printEnvelope(env, out = process.stdout) {
+	out.write(`${escapeJson(JSON.stringify(env, null, 2))}\n`);
+}
+//#endregion
+//#region src/host/prompt.ts
+const ATTEMPTS = 3;
+const NUMBER = /^\d+$/;
+/** How much of an unrecognised answer the retry line quotes back. */
+const ANSWER_MAX = 40;
+/** Room for a name sanitize capped at 120 characters and the portal ID the target selector puts after it. */
+const LABEL_MAX = 160;
+/** Room for a line of a summary shown before a question: a step title with its risk and labels. */
+const LINE_MAX = 400;
+/**
+* A Prompter reading answers from `input` and writing the questions, the choices, any summary and any retry line to
+* `output`. Lines read ahead of a question, such as a second answer piped in with the first, wait for the next one.
+*/
+function createPrompter(input, output) {
+	const lines = lineQueue(input, output);
+	return {
+		choose(question, choices) {
+			return lines.session(async (next) => {
+				const ask = `Enter 1-${choices.length} or a name: `;
+				output.write(`${sanitize(question)}\n`);
+				choices.forEach((choice, i) => {
+					output.write(`  ${i + 1}) ${sanitize(choice.label, LABEL_MAX)}\n`);
+				});
+				const attempt = async (left) => {
+					const answer = left > 0 ? await next(ask) : void 0;
+					if (answer === void 0) return;
+					const picked = pick(answer, choices);
+					if (picked !== void 0) return picked;
+					output.write(`'${sanitize(answer, ANSWER_MAX)}' is not one of the ${choices.length} choices.\n`);
+					return await attempt(left - 1);
+				};
+				return await attempt(ATTEMPTS);
+			});
+		},
+		ask(question) {
+			return lines.session((next) => next(`${sanitize(question)} `));
+		},
+		tell(text) {
+			for (const line of text) output.write(`${sanitize(line, LINE_MAX)}\n`);
+		}
+	};
+}
+function lineQueue(input, output) {
+	const queued = [];
+	let ended = false;
+	async function session(ask) {
+		ended ||= input.readableEnded === true;
+		if (ended) return ask((prompt) => {
+			output.write(prompt);
+			return Promise.resolve(take());
+		});
+		const terminal = input.isTTY === true;
+		const rl = createInterface({
+			input,
+			output: toStream(output),
+			terminal
+		});
+		const waiting = [];
+		let closing = false;
+		let closed = false;
+		rl.on("line", (line) => {
+			const waiter = waiting.shift();
+			if (waiter) waiter(line);
+			else queued.push(line);
+		});
+		rl.once("close", () => {
+			closed = true;
+			ended ||= !closing;
+			for (const waiter of waiting.splice(0)) {
+				output.write("\n");
+				waiter(void 0);
+			}
+		});
+		rl.on("SIGINT", () => rl.close());
+		const next = (prompt) => {
+			if (closed) output.write(prompt);
+			else {
+				rl.setPrompt(prompt);
+				rl.prompt();
+			}
+			if (queued.length > 0 || closed) return Promise.resolve(take());
+			return new Promise((resolve) => waiting.push(resolve));
+		};
+		try {
+			return await ask(next);
+		} finally {
+			closing = true;
+			rl.close();
+		}
+	}
+	function take() {
+		const line = queued.shift();
+		if (line === void 0) output.write("\n");
+		return line;
+	}
+	return { session };
+}
+function pick(answer, choices) {
+	const trimmed = answer.trim();
+	const n = NUMBER.test(trimmed) ? Number(trimmed) : 0;
+	if (n >= 1 && n <= choices.length) return choices[n - 1]?.value;
+	return choices.find((choice) => choice.value === answer || choice.value === trimmed)?.value;
+}
+function toStream(out) {
+	if (out instanceof Writable) return out;
+	return new Writable({ write(chunk, _encoding, callback) {
+		out.write(chunk.toString());
+		callback();
+	} });
+}
+//#endregion
+//#region src/host/host.ts
+const HELP_WIDTH = 100;
+const PROGRESS_MAX = 200;
+/** A person is at a terminal when stdin and stderr are terminals and CI is not set. The entry passes the process's. */
+function isInteractive(stdin, stderr, env) {
+	return stdin.isTTY === true && stderr.isTTY === true && !env.CI;
+}
+/** Runs one invocation and returns its exit code. Only the executable entry sets process.exitCode. */
+async function run(argv, io) {
+	const json = argv.includes("--json");
+	const invocation = {};
+	const prompt = io.interactive === true && !json && io.stdin ? createPrompter(io.stdin, io.stderr) : void 0;
+	try {
+		const result = await dispatch(argv, io.cwd, invocation, prompt, io);
+		const exitCode = result.exitCode ?? exitCodes.done;
+		const issues = withDocs(result.issues ?? []);
+		if (json) printEnvelope(envelope(exitCode === exitCodes.done || exitCode === exitCodes.differences, result.data, issues), io.stdout);
+		else {
+			if (result.text) io.stdout.write(result.text);
+			printLines(issues, io.stderr);
+		}
+		return exitCode;
+	} catch (error) {
+		const failed = failure(error);
+		const issues = withDocs(failed.issues);
+		if (json) printEnvelope(envelope(false, void 0, issues), io.stdout);
+		else {
+			printLines(issues, io.stderr);
+			if (invocation.config && issues.some((issue) => issue.code === "E_USAGE")) io.stderr.write(`\n${await helpText(invocation.config, invocation.id)}\n`);
+		}
+		return failed.exitCode;
+	}
+}
+/**
+* Parses and runs one invocation and returns its result without printing anything. Errors are thrown as they
+* happen; `run` turns them into issues and an exit code. Without `prompt` nothing asks, as in a run without a terminal.
+*/
+function execute(argv, cwd, prompt) {
+	return dispatch(argv, cwd, {}, prompt);
+}
+async function dispatch(argv, cwd, invocation, prompt, io) {
+	const config = await loadConfig();
+	invocation.config = config;
+	const { id, rest } = splitCommand(argv, config);
+	if (argv.includes("--version")) return {
+		data: {
+			name: bin,
+			version,
+			disclaimer,
+			formats: [...formats]
+		},
+		text: versionText()
+	};
+	const topic = id !== void 0 && !config.findCommand(id) && isTopic(config, id);
+	invocation.id = id !== void 0 && (config.findCommand(id) || topic) ? id : void 0;
+	if (id === void 0 || topic || argv.includes("--help") || argv.includes("-h")) {
+		const usage = await helpText(config, invocation.id);
+		return {
+			data: { usage },
+			text: `${usage}\n`
+		};
+	}
+	const found = config.findCommand(id);
+	if (!found) throw usageError(`unknown command '${id}'`);
+	const Found = await found.load();
+	const command = new Found(rest, config);
+	if (!(command instanceof KalupCommand)) throw new Error(`command ${id} is not a Kalup command`);
+	command.cwd = cwd;
+	command.prompt = prompt;
+	const stderr = io?.stderr;
+	command.progress = stderr && !argv.includes("--json") ? (line) => stderr.write(`${sanitize(line, PROGRESS_MAX)}\n`) : void 0;
+	const interrupts = Found.interruptible === true && io ? watch(io) : void 0;
+	command.signal = interrupts?.signal;
+	try {
+		return await command.run();
+	} catch (error) {
+		throw fromParser(error);
+	} finally {
+		interrupts?.dispose();
+	}
+}
+/** Exit code of a second signal: the run stopped mid-way, and a write may have landed. */
+const HARD_STOP = exitCodes.partial;
+/**
+* A second signal this soon after the first is the same interrupt: under npx, npm forwards the terminal's SIGINT to
+* its child, which the terminal already sent to the whole process group, so one Ctrl-C arrives twice.
+*/
+const SAME_INTERRUPT_MS = 1e3;
+function watch(io) {
+	const { signals } = io;
+	if (!signals) return;
+	const controller = new AbortController();
+	let first;
+	const listener = () => {
+		if (first === void 0) {
+			first = Date.now();
+			controller.abort();
+			io.stderr.write("Stopping after the request in flight. Send the signal again to stop at once.\n");
+			return;
+		}
+		if (Date.now() - first >= SAME_INTERRUPT_MS) io.exit?.(HARD_STOP);
+	};
+	signals.on("SIGINT", listener);
+	signals.on("SIGTERM", listener);
+	return {
+		signal: controller.signal,
+		dispose: () => {
+			signals.off("SIGINT", listener);
+			signals.off("SIGTERM", listener);
+		}
+	};
+}
+let configLoad;
+function loadConfig() {
+	configLoad ??= Config.load({
+		root: packageRoot(),
+		userPlugins: false,
+		devPlugins: false,
+		jitPlugins: false
+	});
+	return configLoad;
+}
+function packageRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (dirname(dir) !== dir) {
+		const file = join(dir, "package.json");
+		if (existsSync(file) && JSON.parse(readFileSync(file, "utf8")).name === "kalup") return dir;
+		dir = dirname(dir);
+	}
+	throw new Error("the kalup package.json was not found above the host module");
+}
+const ROOT_FLAGS = /* @__PURE__ */ new Set([
+	"--json",
+	"--help",
+	"-h",
+	"--version"
+]);
+/**
+* The command id is the first argument that is neither a flag nor a flag's value, so flags may come before or
+* after it. A flag takes a value when any command declares it as an option; `--flag=value` carries its own.
+* Without a command only the root flags are accepted: anything else, even beside --help or --version, is E_USAGE.
+*/
+function splitCommand(argv, config) {
+	const flags = config.commands.flatMap((command) => Object.entries(command.flags));
+	const valued = new Set(flags.filter(([, flag]) => flag.type === "option").map(([name]) => `--${name}`));
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg.startsWith("-")) {
+			if (valued.has(arg)) i += 1;
+			continue;
+		}
+		const next = isTopic(config, arg) ? subcommand(argv, i + 1, valued) : void 0;
+		const id = next === void 0 ? void 0 : `${arg}:${argv[next]}`;
+		if (next !== void 0 && id !== void 0) {
+			if (!config.findCommand(id)) throw usageError(`unknown command '${arg} ${argv[next]}'`);
+			return {
+				id,
+				rest: argv.filter((_, at) => at !== i && at !== next)
+			};
+		}
+		return {
+			id: arg,
+			rest: [...argv.slice(0, i), ...argv.slice(i + 1)]
+		};
+	}
+	const stray = argv.find((arg) => !ROOT_FLAGS.has(arg));
+	if (stray !== void 0) {
+		const [name] = stray.split("=");
+		throw usageError(flags.some(([declared]) => `--${declared}` === name) ? `${name} needs a command` : `unknown flag ${stray}`);
+	}
+	return { rest: argv };
+}
+function isTopic(config, id) {
+	return config.commands.some((command) => command.id.startsWith(`${id}:`));
+}
+function subcommand(argv, from, valued) {
+	for (let i = from; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (!arg.startsWith("-")) return i;
+		if (valued.has(arg)) i += 1;
+	}
+}
+/** The help for one command, or for the whole CLI, as oclif renders it, plain text, with the disclaimer. */
+async function helpText(config, id) {
+	const help = new CapturedHelp(config, {
+		maxWidth: HELP_WIDTH,
+		stripAnsi: true
+	});
+	const ids = config.commands.map((command) => [
+		command,
+		command.id,
+		command.aliases
+	]);
+	try {
+		await help.showHelp(id === void 0 ? [] : [id]);
+	} finally {
+		for (const [command, original, aliases] of ids) {
+			command.id = original;
+			command.aliases = aliases;
+		}
+	}
+	return `${help.lines.join("\n").trimEnd()}\n\n${disclaimer}`;
+}
+var CapturedHelp = class extends Help {
+	lines = [];
+	log(...args) {
+		this.lines.push(args.join(" "));
+	}
+};
+function fromParser(error) {
+	if (!(error instanceof Errors.CLIError) || error.oclif.exit !== 2) return error;
+	const { flags, args } = error;
+	if (Array.isArray(flags) && typeof flags[0] === "string") return usageError(`unknown flag ${flags[0]}`);
+	if (Array.isArray(args) && typeof args[0] === "string") return usageError(`unexpected argument '${args[0]}'`);
+	if (Array.isArray(args) && args.length > 0) {
+		const names = args.map((arg) => arg.name.toUpperCase());
+		return usageError(`missing argument${names.length > 1 ? "s" : ""} ${names.join(", ")}`);
+	}
+	return usageError(sanitize(error.message.split("\n")[0] ?? ""));
+}
+function failure(error) {
+	if (error instanceof KalupError) return error;
+	if (error instanceof IssueError) return {
+		issues: error.issues,
+		exitCode: exitCodes.invalid
+	};
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		issues: [{
+			code: "E_UNEXPECTED",
+			message: sanitize(message.split("\n")[0] ?? "")
+		}],
+		exitCode: exitCodes.error
+	};
+}
+/** Points each issue at its page in the shipped docs folder. test/docs.test.ts checks every code has one. */
+function withDocs(issues) {
+	return issues.map((issue) => ({
+		...issue,
+		docs: issue.docs ?? `errors/${issue.code}.md`
+	}));
+}
+/**
+* One line per issue: `file:line: CODE: message (fix: ...) (docs: ...)`. A file named on the command line is text, and
+* a message or fix can quote kalup.config.ts (a target name, defaultTarget), so each is sanitized, never shortened.
+*/
+function formatIssue(issue) {
+	const where = issue.file ? `${sanitize(issue.file, PATH_MAX)}${issue.line === void 0 ? "" : `:${issue.line}`}: ` : "";
+	const fix = issue.fix ? ` (fix: ${sanitize(issue.fix, Number.POSITIVE_INFINITY)})` : "";
+	const docs = issue.docs ? ` (docs: ${issue.docs})` : "";
+	return `${where}${issue.code}: ${sanitize(issue.message, Number.POSITIVE_INFINITY)}${fix}${docs}`;
+}
+function printLines(issues, out) {
+	if (issues.length > 0) out.write(`${issues.map(formatIssue).join("\n")}\n`);
+}
+//#endregion
+export { isInteractive as n, run as r, execute as t };

package/dist/host.d.mts

@@ -0,0 +1,44 @@
+import { i as ExitCode, n as Prompter, r as Result } from "./context-D10Syqfd.mjs";
+//#region src/host/host.d.ts
+interface Out {
+  write: (text: string) => unknown;
+}
+type Signal = 'SIGINT' | 'SIGTERM';
+/** Where SIGINT and SIGTERM arrive: the process, or a test's emitter. */
+export interface Signals {
+  off: (signal: Signal, listener: () => void) => unknown;
+  on: (signal: Signal, listener: () => void) => unknown;
+}
+export interface Io {
+  cwd: string;
+  /** Ends the process at once, on a second signal during an interruptible command. */
+  exit?: (code: number) => void;
+  /**
+   * Whether a person is at a terminal: stdin and stderr are terminals and CI is not set. The entry decides it from the
+   * process; a command prompts only when this is true, stdin is given and --json is absent.
+   */
+  interactive?: boolean;
+  /**
+   * The process's signals. While an interruptible command runs (apply), the first SIGINT or SIGTERM aborts its signal,
+   * so it stops before its next request, and a second one a second or more later exits at once.
+   */
+  signals?: Signals;
+  stderr: Out;
+  /** Where a prompt reads its answer. */
+  stdin?: NodeJS.ReadableStream;
+  stdout: Out;
+}
+/** A person is at a terminal when stdin and stderr are terminals and CI is not set. The entry passes the process's. */
+export declare function isInteractive(stdin: {
+  isTTY?: boolean;
+}, stderr: {
+  isTTY?: boolean;
+}, env: NodeJS.ProcessEnv): boolean;
+/** Runs one invocation and returns its exit code. Only the executable entry sets process.exitCode. */
+export declare function run(argv: string[], io: Io): Promise<ExitCode>;
+/**
+ * Parses and runs one invocation and returns its result without printing anything. Errors are thrown as they
+ * happen; `run` turns them into issues and an exit code. Without `prompt` nothing asks, as in a run without a terminal.
+ */
+export declare function execute(argv: string[], cwd: string, prompt?: Prompter): Promise<Result>;
+//#endregion

package/dist/host.mjs

@@ -0,0 +1,2 @@
+import { n as isInteractive, r as run, t as execute } from "./host-BJWvo3sX.mjs";
+export { execute, isInteractive, run };

package/dist/index.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/index.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { n as isInteractive, r as run } from "./host-BJWvo3sX.mjs";
+//#region src/index.ts
+process.exitCode = await run(process.argv.slice(2), {
+	cwd: process.cwd(),
+	stdin: process.stdin,
+	interactive: isInteractive(process.stdin, process.stderr, process.env),
+	signals: process,
+	exit: (code) => process.exit(code),
+	stdout: process.stdout,
+	stderr: process.stderr
+});
+//#endregion
+export {};

package/dist/schemas/blueprint-1.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kalup.dev/schemas/blueprint-1.schema.json",
+  "title": "Kalup blueprint, version 1",
+  "description": "A versioned, data-only fragment of IR that `kalup add` renders into a project's config files. Groups and managed properties only, in IR form. Closed at every level: a field this schema does not list is an error. No code runs, ever.",
+  "type": "object",
+  "required": ["blueprintVersion", "name", "version", "irVersion", "resources"],
+  "properties": {
+    "blueprintVersion": { "const": 1 },
+    "name": {
+      "description": "One or two segments of lowercase letters and digits joined by single dashes, `acme/renewals` for example. A segment never holds two dashes in a row, so the stored original's file name, the slash written as two dashes, names one blueprint.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)?$"
+    },
+    "version": { "$ref": "#/$defs/version" },
+    "irVersion": { "const": 1 },
+    "description": {
+      "description": "The author's own text. Printed only to a person at a terminal, labelled as third-party text.",
+      "type": "string"
+    },
+    "requires": {
+      "description": "The objects the project must provide.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/objectRef" }
+    },
+    "resources": {
+      "type": "object",
+      "patternProperties": { "^[a-z]+:\\S+$": { "$ref": "#/$defs/resource" } },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "version": {
+      "description": "Semantic version MAJOR.MINOR.PATCH with an optional pre-release.",
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "address": {
+      "type": "string",
+      "pattern": "^[a-z]+:\\S+$"
+    },
+    "ref": {
+      "type": "object",
+      "required": ["$ref"],
+      "properties": { "$ref": { "$ref": "#/$defs/address" } },
+      "additionalProperties": false
+    },
+    "objectRef": {
+      "type": "object",
+      "required": ["$ref"],
+      "properties": { "$ref": { "type": "string", "pattern": "^object:[a-z][a-z0-9_]*$" } },
+      "additionalProperties": false
+    },
+    "resource": {
+      "type": "object",
+      "required": ["type", "definition"],
+      "properties": {
+        "type": { "enum": ["group", "property"] },
+        "definition": { "type": "object" },
+        "binding": { "$ref": "#/$defs/binding" },
+        "lifecycle": { "$ref": "#/$defs/lifecycle" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": { "required": ["type"], "properties": { "type": { "const": "property" } } },
+          "then": { "properties": { "definition": { "$ref": "#/$defs/propertyDefinition" } } }
+        },
+        {
+          "if": { "required": ["type"], "properties": { "type": { "const": "group" } } },
+          "then": {
+            "description": "A group has a label and nothing else.",
+            "properties": { "type": {}, "definition": { "$ref": "#/$defs/groupDefinition" } },
+            "additionalProperties": false
+          }
+        }
+      ]
+    },
+    "propertyDefinition": {
+      "description": "A managed property definition in HubSpot terms, as the IR holds it.",
+      "type": "object",
+      "required": ["label", "group", "type", "fieldType"],
+      "properties": {
+        "label": { "type": "string" },
+        "group": { "$ref": "#/$defs/ref" },
+        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration"] },
+        "fieldType": {
+          "enum": [
+            "text",
+            "textarea",
+            "file",
+            "phonenumber",
+            "number",
+            "booleancheckbox",
+            "select",
+            "radio",
+            "checkbox",
+            "date"
+          ]
+        },
+        "description": { "type": "string" },
+        "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
+        "hasUniqueValue": { "type": "boolean" },
+        "formField": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "option": {
+      "type": "object",
+      "required": ["value", "label"],
+      "properties": {
+        "value": { "type": "string" },
+        "label": { "type": "string" },
+        "hidden": { "type": "boolean" },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "groupDefinition": {
+      "type": "object",
+      "required": ["label"],
+      "properties": { "label": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "binding": {
+      "description": "App terms. The key defaults to camelCase of the unprefixed name, the codec to the one the HubSpot type implies.",
+      "type": "object",
+      "properties": {
+        "key": { "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
+        "codec": { "enum": ["string", "number", "boolean", "date", "datetime", "enum", "multiEnum", "stringArray"] },
+        "aliases": { "type": "object", "additionalProperties": { "type": "string" } },
+        "required": { "type": "boolean" },
+        "readonly": { "type": "boolean" },
+        "strict": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "lifecycle": {
+      "type": "object",
+      "required": ["options"],
+      "properties": {
+        "options": { "enum": ["additive", "exact"] },
+        "removedOptions": { "type": "array", "items": { "type": "string" } },
+        "ignoreChanges": { "type": "array", "items": { "type": "string" } },
+        "preventDestroy": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/dist/schemas/blueprints-lock-1.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kalup.dev/schemas/blueprints-lock-1.schema.json",
+  "title": "Kalup blueprints lock, version 1",
+  "description": "kalup/blueprints.lock.json, written by `kalup add` and `kalup blueprint upgrade`, never by hand. Records where each blueprint came from, the stored original upgrades merge against, and which config resources it provides. Closed at every level.",
+  "type": "object",
+  "required": ["lockVersion", "blueprints", "sources"],
+  "properties": {
+    "lockVersion": { "const": 1 },
+    "blueprints": {
+      "type": "object",
+      "patternProperties": { "^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)?$": { "$ref": "#/$defs/entry" } },
+      "additionalProperties": false
+    },
+    "sources": {
+      "description": "Every `<source>@<version>` ever recorded, to its hash: the same source and version with another hash is refused.",
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/hash" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "hash": {
+      "description": "sha256: and the hex digest of the bytes as fetched.",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "address": {
+      "type": "string",
+      "pattern": "^(group|property):[^\\s/]+/[^\\s/]+$"
+    },
+    "entry": {
+      "type": "object",
+      "required": ["version", "source", "hash", "prefix", "original", "resources", "held"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+        },
+        "source": {
+          "description": "A path relative to the project root with forward slashes, or an https URL.",
+          "type": "string"
+        },
+        "hash": { "$ref": "#/$defs/hash" },
+        "prefix": { "type": "string", "pattern": "^([a-z][a-z0-9_]*)?$" },
+        "original": {
+          "description": "The stored original, kalup/.blueprints/<name with / as -->@<version>.json.",
+          "type": "string"
+        },
+        "resources": {
+          "description": "Each local address the blueprint provides, to its address in the blueprint.",
+          "type": "object",
+          "patternProperties": { "^(group|property):[^\\s/]+/[^\\s/]+$": { "$ref": "#/$defs/address" } },
+          "additionalProperties": false
+        },
+        "held": {
+          "description": "The conflicts the last upgrade kept config's value for.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/held" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "held": {
+      "type": "object",
+      "required": ["address", "unit"],
+      "properties": {
+        "address": { "$ref": "#/$defs/address" },
+        "unit": { "type": "string" },
+        "local": { "description": "Config's value; absent when config has none." },
+        "remote": { "description": "The upstream value; absent when the blueprint has none." }
+      },
+      "additionalProperties": false
+    }
+  }
+}