@warlock.js/core 5.30.0 → 5.31.0

package/esm/upgrade/run-upgrade.mjs

@@ -0,0 +1,246 @@
+import { detectPackageManager, getInstallCommand } from "../updater/package-manager.mjs";
+import { loadTsMorph } from "./load-ts-morph.mjs";
+import { compareVersions, normalizeVersion, parseVersion } from "./version.mjs";
+import { CODEMODS } from "./codemods/index.mjs";
+import { unifiedDiff } from "./diff.mjs";
+import { UPGRADE_NOTES } from "./notes.mjs";
+import path from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import glob from "fast-glob";
+
+//#region ../../packages/core/src/upgrade/run-upgrade.ts
+/** Thrown for a request the command cannot act on (bad versions, nothing to detect). */
+var UpgradeUsageError = class extends Error {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "UpgradeUsageError";
+	}
+};
+/**
+* Apply the mechanical edits for every breaking change between two releases
+* and list what needs a decision. Writes nothing with `dryRun`.
+*/
+async function runUpgrade(options) {
+	const root = path.resolve(options.root ?? process.cwd());
+	const to = toVersion(options.to);
+	const from = options.from ? toVersion(options.from) : detectInstalledVersion(root);
+	if (compareVersions(from, to) >= 0) throw new UpgradeUsageError(notNewerMessage(from, to, options.from !== void 0));
+	const selected = (options.codemods ?? CODEMODS).filter((codemod) => codemod.version === "target" || compareVersions(codemod.version, from) > 0 && compareVersions(codemod.version, to) <= 0);
+	const tsMorph = await (options.loadTsMorph ?? loadTsMorph)(root);
+	const project = new tsMorph.Project({
+		skipAddingFilesFromTsConfig: true,
+		skipFileDependencyResolution: true,
+		compilerOptions: {
+			jsx: tsMorph.ts.JsxEmit.Preserve,
+			allowJs: false
+		}
+	});
+	const relativePaths = await glob("src/**/*.{ts,tsx}", {
+		cwd: root,
+		ignore: [
+			"**/node_modules/**",
+			"**/dist/**",
+			"**/.warlock/**",
+			"**/*.d.ts"
+		],
+		dot: false
+	});
+	relativePaths.sort();
+	const originals = /* @__PURE__ */ new Map();
+	const sourceFiles = [];
+	for (const relative of relativePaths) {
+		const content = readFileSync(path.join(root, relative), "utf8");
+		originals.set(relative, content);
+		sourceFiles.push(project.createSourceFile(path.join(root, relative), content, { overwrite: true }));
+	}
+	const relativeOf = new Map(sourceFiles.map((sourceFile, index) => [sourceFile, relativePaths[index] ?? ""]));
+	const applied = [];
+	const manual = [];
+	const textFiles = createTextFiles(root);
+	let activeCodemod;
+	const context = {
+		tsMorph,
+		sourceFiles,
+		relativePath: (sourceFile) => relativeOf.get(sourceFile) ?? path.relative(root, sourceFile.getFilePath()).split(path.sep).join("/"),
+		text: {
+			read: (file) => textFiles.read(file),
+			write: (file, content, change) => {
+				textFiles.write(file, content);
+				if (activeCodemod) applied.push({
+					codemod: activeCodemod.id,
+					file,
+					...change
+				});
+			}
+		},
+		targetVersion: to
+	};
+	const summary = [];
+	for (const codemod of selected) {
+		activeCodemod = codemod;
+		const appliedBefore = applied.length;
+		const output = codemod.run(context);
+		for (const finding of output.manual) manual.push({
+			...finding,
+			codemod: codemod.id,
+			skill: codemod.skill
+		});
+		const byFile = /* @__PURE__ */ new Map();
+		for (const edit of output.edits) {
+			const list = byFile.get(edit.file) ?? [];
+			list.push(edit);
+			byFile.set(edit.file, list);
+		}
+		for (const [file, edits] of byFile) {
+			const sourceFile = sourceFiles[relativePaths.indexOf(file)];
+			if (!sourceFile) continue;
+			let content = sourceFile.getFullText();
+			let lowestStart = Number.POSITIVE_INFINITY;
+			for (const edit of [...edits].sort((left, right) => right.start - left.start)) {
+				if (edit.end > lowestStart) {
+					manual.push({
+						codemod: codemod.id,
+						skill: codemod.skill,
+						file,
+						line: edit.line,
+						hint: `Not edited automatically (overlaps another change): ${edit.description}. Run the upgrade again after reviewing.`
+					});
+					continue;
+				}
+				content = content.slice(0, edit.start) + edit.text + content.slice(edit.end);
+				lowestStart = edit.start;
+				applied.push({
+					codemod: codemod.id,
+					file,
+					line: edit.line,
+					description: edit.description
+				});
+			}
+			sourceFile.replaceWithText(content);
+		}
+		summary.push({
+			id: codemod.id,
+			version: codemod.version === "target" ? to : codemod.version,
+			title: codemod.title,
+			applied: applied.length - appliedBefore,
+			manual: manual.filter((item) => item.codemod === codemod.id).length
+		});
+	}
+	activeCodemod = void 0;
+	applied.sort(byFileAndLine);
+	manual.sort(byFileAndLine);
+	const changes = [];
+	sourceFiles.forEach((sourceFile, index) => {
+		const file = relativePaths[index];
+		if (file === void 0) return;
+		const before = originals.get(file) ?? "";
+		const after = sourceFile.getFullText();
+		if (before !== after) changes.push({
+			file,
+			before,
+			after
+		});
+	});
+	for (const change of textFiles.changes()) changes.push(change);
+	changes.sort((left, right) => left.file.localeCompare(right.file));
+	if (!options.dryRun) for (const change of changes) writeFileSync(path.join(root, change.file), change.after);
+	const packageJsonChanged = changes.some((change) => change.file === "package.json" && applied.some((item) => item.codemod === "warlock-versions" && item.file === "package.json"));
+	return {
+		from,
+		to,
+		dryRun: options.dryRun === true,
+		codemods: summary,
+		applied,
+		manual,
+		notes: UPGRADE_NOTES.filter((note) => compareVersions(note.version, from) > 0 && compareVersions(note.version, to) <= 0),
+		changedFiles: changes.map((change) => change.file),
+		diff: changes.map((change) => unifiedDiff(change.file, change.before, change.after)).join(""),
+		...packageJsonChanged && { installHint: getInstallCommand(await detectPackageManager(root)) }
+	};
+}
+/**
+* Explain why `--to` is not newer than the starting version. The usual cause
+* is running the command after installing the new release: the starting
+* version is read from the installed `@warlock.js/core`, which is then already
+* the target, so the command needs `--from`.
+*/
+function notNewerMessage(from, to, fromWasPassed) {
+	if (fromWasPassed) return `--from ${from} is not older than --to ${to}. Pass the version this app is upgrading from.`;
+	const example = `warlock upgrade --from ${previousMinor(to)} --to ${to}`;
+	if (compareVersions(from, to) === 0) return `The installed @warlock.js/core is already ${from}, the --to version, so the version this app is upgrading from cannot be detected. Pass it with --from <previous version>, e.g. ${example}.`;
+	return `This app is already on ${from}; --to ${to} is not newer. If the detected version is wrong, pass --from <previous version>, e.g. ${example}.`;
+}
+/** `5.31.0` → `5.30`. A major's first release has no minor to step back to, so it gets a placeholder. */
+function previousMinor(version) {
+	const [major, minor] = parseVersion(version) ?? [
+		0,
+		0,
+		0
+	];
+	return minor > 0 ? `${major}.${minor - 1}` : "<previous version>";
+}
+function toVersion(value) {
+	try {
+		return normalizeVersion(value);
+	} catch (error) {
+		throw new UpgradeUsageError(error instanceof Error ? error.message : String(error));
+	}
+}
+/** The installed `@warlock.js/core`, or the version its package.json range names. */
+function detectInstalledVersion(root) {
+	const installed = path.join(root, "node_modules", "@warlock.js", "core", "package.json");
+	if (existsSync(installed)) {
+		const version = JSON.parse(readFileSync(installed, "utf8")).version;
+		if (typeof version === "string" && parseVersion(version)) return normalizeVersion(stripRange(version));
+	}
+	const manifest = path.join(root, "package.json");
+	if (existsSync(manifest)) {
+		const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+		const spec = pkg.dependencies?.["@warlock.js/core"] ?? pkg.devDependencies?.["@warlock.js/core"];
+		const parsed = typeof spec === "string" ? parseVersion(spec) : void 0;
+		if (parsed) return parsed.join(".");
+	}
+	throw new UpgradeUsageError("Could not tell which Warlock version this app is on (no installed @warlock.js/core). Pass it with --from, e.g. --from 5.29.");
+}
+function stripRange(version) {
+	return (parseVersion(version) ?? [
+		0,
+		0,
+		0
+	]).join(".");
+}
+function byFileAndLine(left, right) {
+	return left.file.localeCompare(right.file) || left.line - right.line;
+}
+/** Non-TypeScript files a codemod reads and rewrites, buffered until the end. */
+function createTextFiles(root) {
+	const files = /* @__PURE__ */ new Map();
+	const entry = (file) => {
+		let existing = files.get(file);
+		if (!existing) {
+			const absolute = path.join(root, file);
+			const content = existsSync(absolute) ? readFileSync(absolute, "utf8") : void 0;
+			existing = {
+				before: content,
+				current: content
+			};
+			files.set(file, existing);
+		}
+		return existing;
+	};
+	return {
+		read: (file) => entry(file).current,
+		write: (file, content) => {
+			entry(file).current = content;
+		},
+		changes: () => [...files.entries()].filter(([, value]) => value.current !== void 0 && value.current !== value.before).map(([file, value]) => ({
+			file,
+			before: value.before ?? "",
+			after: value.current ?? ""
+		}))
+	};
+}
+
+//#endregion
+export { UpgradeUsageError, runUpgrade };
+//# sourceMappingURL=run-upgrade.mjs.map

package/esm/upgrade/run-upgrade.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-upgrade.mjs","names":[],"sources":["../../../../../../../../packages/core/src/upgrade/run-upgrade.ts"],"sourcesContent":["import glob from \"fast-glob\";\nimport { existsSync, readFileSync, writeFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { detectPackageManager, getInstallCommand } from \"../updater/package-manager\";\nimport { CODEMODS } from \"./codemods\";\nimport { unifiedDiff } from \"./diff\";\nimport { loadTsMorph } from \"./load-ts-morph\";\nimport { UPGRADE_NOTES } from \"./notes\";\nimport type {\n  AppliedChange,\n  Codemod,\n  CodemodContext,\n  ManualItem,\n  SourceEdit,\n  SourceFile,\n  TextFiles,\n  TsMorphModule,\n  UpgradeResult,\n} from \"./types\";\nimport { compareVersions, normalizeVersion, parseVersion } from \"./version\";\n\nexport type RunUpgradeOptions = {\n  /** App root. Defaults to the current directory. */\n  root?: string;\n  /** Target version, e.g. `5.31` or `5.31.0`. */\n  to: string;\n  /** Version upgrading from; detected from the installed `@warlock.js/core` when omitted. */\n  from?: string;\n  /** Compute and report everything, write nothing. */\n  dryRun?: boolean;\n  /** Override the codemod list (tests). */\n  codemods?: readonly Codemod[];\n  /** Override how ts-morph is loaded (tests). */\n  loadTsMorph?: (root: string) => Promise<TsMorphModule>;\n};\n\n/** Thrown for a request the command cannot act on (bad versions, nothing to detect). */\nexport class UpgradeUsageError extends Error {\n  public override readonly name = \"UpgradeUsageError\";\n}\n\n/**\n * Apply the mechanical edits for every breaking change between two releases\n * and list what needs a decision. Writes nothing with `dryRun`.\n */\nexport async function runUpgrade(options: RunUpgradeOptions): Promise<UpgradeResult> {\n  const root = path.resolve(options.root ?? process.cwd());\n  const to = toVersion(options.to);\n  const from = options.from ? toVersion(options.from) : detectInstalledVersion(root);\n\n  if (compareVersions(from, to) >= 0) {\n    throw new UpgradeUsageError(notNewerMessage(from, to, options.from !== undefined));\n  }\n\n  const selected = (options.codemods ?? CODEMODS).filter(\n    (codemod) =>\n      codemod.version === \"target\" ||\n      (compareVersions(codemod.version, from) > 0 && compareVersions(codemod.version, to) <= 0),\n  );\n\n  const tsMorph = await (options.loadTsMorph ?? loadTsMorph)(root);\n  const project = new tsMorph.Project({\n    skipAddingFilesFromTsConfig: true,\n    skipFileDependencyResolution: true,\n    compilerOptions: { jsx: tsMorph.ts.JsxEmit.Preserve, allowJs: false },\n  });\n\n  const relativePaths = await glob(\"src/**/*.{ts,tsx}\", {\n    cwd: root,\n    ignore: [\"**/node_modules/**\", \"**/dist/**\", \"**/.warlock/**\", \"**/*.d.ts\"],\n    dot: false,\n  });\n  relativePaths.sort();\n\n  const originals = new Map<string, string>();\n  const sourceFiles: SourceFile[] = [];\n  for (const relative of relativePaths) {\n    const content = readFileSync(path.join(root, relative), \"utf8\");\n    originals.set(relative, content);\n    sourceFiles.push(\n      project.createSourceFile(path.join(root, relative), content, { overwrite: true }),\n    );\n  }\n\n  const relativeOf = new Map<SourceFile, string>(\n    sourceFiles.map((sourceFile, index) => [sourceFile, relativePaths[index] ?? \"\"]),\n  );\n\n  const applied: AppliedChange[] = [];\n  const manual: ManualItem[] = [];\n  const textFiles = createTextFiles(root);\n  let activeCodemod: Codemod | undefined;\n\n  const text: TextFiles = {\n    read: (file) => textFiles.read(file),\n    write: (file, content, change) => {\n      textFiles.write(file, content);\n      if (activeCodemod) {\n        applied.push({ codemod: activeCodemod.id, file, ...change });\n      }\n    },\n  };\n\n  const context: CodemodContext = {\n    tsMorph,\n    sourceFiles,\n    relativePath: (sourceFile) =>\n      relativeOf.get(sourceFile) ??\n      path.relative(root, sourceFile.getFilePath()).split(path.sep).join(\"/\"),\n    text,\n    targetVersion: to,\n  };\n\n  const summary: UpgradeResult[\"codemods\"] = [];\n\n  for (const codemod of selected) {\n    activeCodemod = codemod;\n    const appliedBefore = applied.length;\n    const output = codemod.run(context);\n\n    for (const finding of output.manual) {\n      manual.push({ ...finding, codemod: codemod.id, skill: codemod.skill });\n    }\n\n    const byFile = new Map<string, SourceEdit[]>();\n    for (const edit of output.edits) {\n      const list = byFile.get(edit.file) ?? [];\n      list.push(edit);\n      byFile.set(edit.file, list);\n    }\n\n    for (const [file, edits] of byFile) {\n      const sourceFile = sourceFiles[relativePaths.indexOf(file)];\n      if (!sourceFile) continue;\n\n      let content = sourceFile.getFullText();\n      let lowestStart = Number.POSITIVE_INFINITY;\n      for (const edit of [...edits].sort((left, right) => right.start - left.start)) {\n        // Overlapping edits (one inside another) would corrupt the file: keep the outer one.\n        if (edit.end > lowestStart) {\n          manual.push({\n            codemod: codemod.id,\n            skill: codemod.skill,\n            file,\n            line: edit.line,\n            hint: `Not edited automatically (overlaps another change): ${edit.description}. Run the upgrade again after reviewing.`,\n          });\n          continue;\n        }\n        content = content.slice(0, edit.start) + edit.text + content.slice(edit.end);\n        lowestStart = edit.start;\n        applied.push({ codemod: codemod.id, file, line: edit.line, description: edit.description });\n      }\n\n      sourceFile.replaceWithText(content);\n    }\n\n    summary.push({\n      id: codemod.id,\n      version: codemod.version === \"target\" ? to : codemod.version,\n      title: codemod.title,\n      applied: applied.length - appliedBefore,\n      manual: manual.filter((item) => item.codemod === codemod.id).length,\n    });\n  }\n  activeCodemod = undefined;\n\n  applied.sort(byFileAndLine);\n  manual.sort(byFileAndLine);\n\n  const changes: { file: string; before: string; after: string }[] = [];\n  sourceFiles.forEach((sourceFile, index) => {\n    const file = relativePaths[index];\n    if (file === undefined) return;\n    const before = originals.get(file) ?? \"\";\n    const after = sourceFile.getFullText();\n    if (before !== after) changes.push({ file, before, after });\n  });\n  for (const change of textFiles.changes()) changes.push(change);\n  changes.sort((left, right) => left.file.localeCompare(right.file));\n\n  if (!options.dryRun) {\n    for (const change of changes) writeFileSync(path.join(root, change.file), change.after);\n  }\n\n  const packageJsonChanged = changes.some(\n    (change) =>\n      change.file === \"package.json\" &&\n      applied.some((item) => item.codemod === \"warlock-versions\" && item.file === \"package.json\"),\n  );\n\n  return {\n    from,\n    to,\n    dryRun: options.dryRun === true,\n    codemods: summary,\n    applied,\n    manual,\n    notes: UPGRADE_NOTES.filter(\n      (note) => compareVersions(note.version, from) > 0 && compareVersions(note.version, to) <= 0,\n    ),\n    changedFiles: changes.map((change) => change.file),\n    diff: changes.map((change) => unifiedDiff(change.file, change.before, change.after)).join(\"\"),\n    ...(packageJsonChanged && {\n      installHint: getInstallCommand(await detectPackageManager(root)),\n    }),\n  };\n}\n\n/**\n * Explain why `--to` is not newer than the starting version. The usual cause\n * is running the command after installing the new release: the starting\n * version is read from the installed `@warlock.js/core`, which is then already\n * the target, so the command needs `--from`.\n */\nfunction notNewerMessage(from: string, to: string, fromWasPassed: boolean): string {\n  if (fromWasPassed) {\n    return `--from ${from} is not older than --to ${to}. Pass the version this app is upgrading from.`;\n  }\n\n  const example = `warlock upgrade --from ${previousMinor(to)} --to ${to}`;\n\n  if (compareVersions(from, to) === 0) {\n    return `The installed @warlock.js/core is already ${from}, the --to version, so the version this app is upgrading from cannot be detected. Pass it with --from <previous version>, e.g. ${example}.`;\n  }\n\n  return `This app is already on ${from}; --to ${to} is not newer. If the detected version is wrong, pass --from <previous version>, e.g. ${example}.`;\n}\n\n/** `5.31.0` → `5.30`. A major's first release has no minor to step back to, so it gets a placeholder. */\nfunction previousMinor(version: string): string {\n  const [major, minor] = parseVersion(version) ?? [0, 0, 0];\n\n  return minor > 0 ? `${major}.${minor - 1}` : \"<previous version>\";\n}\n\nfunction toVersion(value: string): string {\n  try {\n    return normalizeVersion(value);\n  } catch (error) {\n    throw new UpgradeUsageError(error instanceof Error ? error.message : String(error));\n  }\n}\n\n/** The installed `@warlock.js/core`, or the version its package.json range names. */\nexport function detectInstalledVersion(root: string): string {\n  const installed = path.join(root, \"node_modules\", \"@warlock.js\", \"core\", \"package.json\");\n  if (existsSync(installed)) {\n    const version = (JSON.parse(readFileSync(installed, \"utf8\")) as { version?: unknown }).version;\n    if (typeof version === \"string\" && parseVersion(version))\n      return normalizeVersion(stripRange(version));\n  }\n\n  const manifest = path.join(root, \"package.json\");\n  if (existsSync(manifest)) {\n    const pkg = JSON.parse(readFileSync(manifest, \"utf8\")) as {\n      dependencies?: Record<string, unknown>;\n      devDependencies?: Record<string, unknown>;\n    };\n    const spec =\n      pkg.dependencies?.[\"@warlock.js/core\"] ?? pkg.devDependencies?.[\"@warlock.js/core\"];\n    const parsed = typeof spec === \"string\" ? parseVersion(spec) : undefined;\n    if (parsed) return parsed.join(\".\");\n  }\n\n  throw new UpgradeUsageError(\n    \"Could not tell which Warlock version this app is on (no installed @warlock.js/core). Pass it with --from, e.g. --from 5.29.\",\n  );\n}\n\nfunction stripRange(version: string): string {\n  return (parseVersion(version) ?? [0, 0, 0]).join(\".\");\n}\n\nfunction byFileAndLine(\n  left: { file: string; line: number },\n  right: { file: string; line: number },\n) {\n  return left.file.localeCompare(right.file) || left.line - right.line;\n}\n\n/** Non-TypeScript files a codemod reads and rewrites, buffered until the end. */\nfunction createTextFiles(root: string) {\n  const files = new Map<string, { before: string | undefined; current: string | undefined }>();\n\n  const entry = (file: string) => {\n    let existing = files.get(file);\n    if (!existing) {\n      const absolute = path.join(root, file);\n      const content = existsSync(absolute) ? readFileSync(absolute, \"utf8\") : undefined;\n      existing = { before: content, current: content };\n      files.set(file, existing);\n    }\n    return existing;\n  };\n\n  return {\n    read: (file: string) => entry(file).current,\n    write: (file: string, content: string) => {\n      entry(file).current = content;\n    },\n    changes: () =>\n      [...files.entries()]\n        .filter(([, value]) => value.current !== undefined && value.current !== value.before)\n        .map(([file, value]) => ({ file, before: value.before ?? \"\", after: value.current ?? \"\" })),\n  };\n}\n"],"mappings":"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"}

package/esm/upgrade/upgrade-command.action.mjs

@@ -0,0 +1,37 @@
+import { formatUpgradeReport } from "./format-upgrade-report.mjs";
+import { TsMorphMissingError } from "./load-ts-morph.mjs";
+import { UpgradeUsageError, runUpgrade } from "./run-upgrade.mjs";
+
+//#region ../../packages/core/src/upgrade/upgrade-command.action.ts
+/**
+* The `warlock upgrade` action. Returns the exit code it set: 0 when it ran
+* (even with places to review), 1 for unusable arguments or a missing ts-morph.
+*/
+async function runUpgradeCommand(options, overrides = {}, output = console) {
+	const json = Boolean(options.json);
+	const fail = (message) => {
+		if (json) output.log(JSON.stringify({ error: message }, null, 2));
+		else output.error(message);
+		process.exitCode = 1;
+		return 1;
+	};
+	const to = typeof options.to === "string" || typeof options.to === "number" ? String(options.to) : "";
+	if (!to) return fail("Pass the version to upgrade to, and the version upgrading from once the new release is installed: warlock upgrade --from 5.30 --to 5.31.0");
+	try {
+		const result = await runUpgrade({
+			...overrides,
+			to,
+			...options.from !== void 0 && options.from !== true && { from: String(options.from) },
+			dryRun: Boolean(options.dryRun)
+		});
+		output.log(json ? JSON.stringify(result, null, 2) : formatUpgradeReport(result));
+		return 0;
+	} catch (error) {
+		if (error instanceof UpgradeUsageError || error instanceof TsMorphMissingError) return fail(error.message);
+		throw error;
+	}
+}
+
+//#endregion
+export { runUpgradeCommand };
+//# sourceMappingURL=upgrade-command.action.mjs.map

package/esm/upgrade/upgrade-command.action.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-command.action.mjs","names":[],"sources":["../../../../../../../../packages/core/src/upgrade/upgrade-command.action.ts"],"sourcesContent":["import { formatUpgradeReport } from \"./format-upgrade-report\";\nimport { TsMorphMissingError } from \"./load-ts-morph\";\nimport { type RunUpgradeOptions, runUpgrade, UpgradeUsageError } from \"./run-upgrade\";\n\ntype Output = { log(message: string): void; error(message: string): void };\n\n/**\n * The `warlock upgrade` action. Returns the exit code it set: 0 when it ran\n * (even with places to review), 1 for unusable arguments or a missing ts-morph.\n */\nexport async function runUpgradeCommand(\n  options: Record<string, string | boolean | number>,\n  overrides: Pick<RunUpgradeOptions, \"root\" | \"codemods\" | \"loadTsMorph\"> = {},\n  output: Output = console,\n): Promise<number> {\n  const json = Boolean(options.json);\n  const fail = (message: string): number => {\n    if (json) output.log(JSON.stringify({ error: message }, null, 2));\n    else output.error(message);\n    process.exitCode = 1;\n    return 1;\n  };\n\n  const to =\n    typeof options.to === \"string\" || typeof options.to === \"number\" ? String(options.to) : \"\";\n  if (!to) {\n    return fail(\n      \"Pass the version to upgrade to, and the version upgrading from once the new release is installed: warlock upgrade --from 5.30 --to 5.31.0\",\n    );\n  }\n\n  try {\n    const result = await runUpgrade({\n      ...overrides,\n      to,\n      ...(options.from !== undefined && options.from !== true && { from: String(options.from) }),\n      dryRun: Boolean(options.dryRun),\n    });\n\n    output.log(json ? JSON.stringify(result, null, 2) : formatUpgradeReport(result));\n    return 0;\n  } catch (error) {\n    if (error instanceof UpgradeUsageError || error instanceof TsMorphMissingError) {\n      return fail(error.message);\n    }\n    throw error;\n  }\n}\n"],"mappings":";;;;;;;;;AAUA,eAAsB,kBACpB,SACA,YAA0E,CAAC,GAC3E,SAAiB,SACA;CACjB,MAAM,OAAO,QAAQ,QAAQ,IAAI;CACjC,MAAM,QAAQ,YAA4B;EACxC,IAAI,MAAM,OAAO,IAAI,KAAK,UAAU,EAAE,OAAO,QAAQ,GAAG,MAAM,CAAC,CAAC;OAC3D,OAAO,MAAM,OAAO;EACzB,QAAQ,WAAW;EACnB,OAAO;CACT;CAEA,MAAM,KACJ,OAAO,QAAQ,OAAO,YAAY,OAAO,QAAQ,OAAO,WAAW,OAAO,QAAQ,EAAE,IAAI;CAC1F,IAAI,CAAC,IACH,OAAO,KACL,2IACF;CAGF,IAAI;EACF,MAAM,SAAS,MAAM,WAAW;GAC9B,GAAG;GACH;GACA,GAAI,QAAQ,SAAS,UAAa,QAAQ,SAAS,QAAQ,EAAE,MAAM,OAAO,QAAQ,IAAI,EAAE;GACxF,QAAQ,QAAQ,QAAQ,MAAM;EAChC,CAAC;EAED,OAAO,IAAI,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC,IAAI,oBAAoB,MAAM,CAAC;EAC/E,OAAO;CACT,SAAS,OAAO;EACd,IAAI,iBAAiB,qBAAqB,iBAAiB,qBACzD,OAAO,KAAK,MAAM,OAAO;EAE3B,MAAM;CACR;AACF"}

package/esm/upgrade/version.mjs

@@ -0,0 +1,39 @@
+//#region ../../packages/core/src/upgrade/version.ts
+/** Parse `5.31`, `5.31.0`, `v5.31.2`, `^5.30.0` into `[major, minor, patch]`. */
+function parseVersion(value) {
+	const match = /(\d{1,6})(?:\.(\d{1,6}))?(?:\.(\d{1,6}))?/.exec(value.trim());
+	if (!match) return void 0;
+	return [
+		Number(match[1]),
+		Number(match[2] ?? 0),
+		Number(match[3] ?? 0)
+	];
+}
+/** `5.31` → `5.31.0`; throws on something that is not a version. */
+function normalizeVersion(value) {
+	const parsed = parseVersion(value);
+	if (!parsed || !/^v?\d{1,6}(\.\d{1,6}){0,2}$/.test(value.trim())) throw new Error(`"${value}" is not a version. Pass one like --to 5.31 or --to 5.31.0.`);
+	return parsed.join(".");
+}
+/** Negative when `left` is older than `right`, 0 when equal, positive when newer. */
+function compareVersions(left, right) {
+	const a = parseVersion(left) ?? [
+		0,
+		0,
+		0
+	];
+	const b = parseVersion(right) ?? [
+		0,
+		0,
+		0
+	];
+	for (let index = 0; index < 3; index++) {
+		const difference = (a[index] ?? 0) - (b[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+//#endregion
+export { compareVersions, normalizeVersion, parseVersion };
+//# sourceMappingURL=version.mjs.map

package/esm/upgrade/version.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.mjs","names":[],"sources":["../../../../../../../../packages/core/src/upgrade/version.ts"],"sourcesContent":["/** Parse `5.31`, `5.31.0`, `v5.31.2`, `^5.30.0` into `[major, minor, patch]`. */\nexport function parseVersion(value: string): [number, number, number] | undefined {\n  const match = /(\\d{1,6})(?:\\.(\\d{1,6}))?(?:\\.(\\d{1,6}))?/.exec(value.trim());\n  if (!match) return undefined;\n\n  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];\n}\n\n/** `5.31` → `5.31.0`; throws on something that is not a version. */\nexport function normalizeVersion(value: string): string {\n  const parsed = parseVersion(value);\n  if (!parsed || !/^v?\\d{1,6}(\\.\\d{1,6}){0,2}$/.test(value.trim())) {\n    throw new Error(`\"${value}\" is not a version. Pass one like --to 5.31 or --to 5.31.0.`);\n  }\n\n  return parsed.join(\".\");\n}\n\n/** Negative when `left` is older than `right`, 0 when equal, positive when newer. */\nexport function compareVersions(left: string, right: string): number {\n  const a = parseVersion(left) ?? [0, 0, 0];\n  const b = parseVersion(right) ?? [0, 0, 0];\n\n  for (let index = 0; index < 3; index++) {\n    const difference = (a[index] ?? 0) - (b[index] ?? 0);\n    if (difference !== 0) return difference;\n  }\n\n  return 0;\n}\n"],"mappings":";;AACA,SAAgB,aAAa,OAAqD;CAChF,MAAM,QAAQ,4CAA4C,KAAK,MAAM,KAAK,CAAC;CAC3E,IAAI,CAAC,OAAO,OAAO;CAEnB,OAAO;EAAC,OAAO,MAAM,EAAE;EAAG,OAAO,MAAM,MAAM,CAAC;EAAG,OAAO,MAAM,MAAM,CAAC;CAAC;AACxE;;AAGA,SAAgB,iBAAiB,OAAuB;CACtD,MAAM,SAAS,aAAa,KAAK;CACjC,IAAI,CAAC,UAAU,CAAC,8BAA8B,KAAK,MAAM,KAAK,CAAC,GAC7D,MAAM,IAAI,MAAM,IAAI,MAAM,4DAA4D;CAGxF,OAAO,OAAO,KAAK,GAAG;AACxB;;AAGA,SAAgB,gBAAgB,MAAc,OAAuB;CACnE,MAAM,IAAI,aAAa,IAAI,KAAK;EAAC;EAAG;EAAG;CAAC;CACxC,MAAM,IAAI,aAAa,KAAK,KAAK;EAAC;EAAG;EAAG;CAAC;CAEzC,KAAK,IAAI,QAAQ,GAAG,QAAQ,GAAG,SAAS;EACtC,MAAM,cAAc,EAAE,UAAU,MAAM,EAAE,UAAU;EAClD,IAAI,eAAe,GAAG,OAAO;CAC/B;CAEA,OAAO;AACT"}

package/esm/use-cases/use-cases-registry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-cases-registry.mjs","names":[],"sources":["../../../../../../../../packages/core/src/use-cases/use-cases-registry.ts"],"sourcesContent":["import { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport { config } from \"../config\";\nimport { type RegisteredUseCase, type UseCaseConfigurations, type UseCaseResult } from \"./types\";\n\n/**\n * Store registered use cases\n */\nconst useCaseRegister = new Map<string, RegisteredUseCase>();\n\n/**\n * Register a use case\n */\nexport function $registerUseCase<Output, Input>(\n  name: string,\n  useCase: RegisteredUseCase<Output, Input>,\n) {\n  if (useCaseRegister.has(name) && process.env.NODE_ENV !== \"production\") {\n    log.warn(\"use-cases\", \"registering\", `Use case \"${name}\" is already registered. Overwriting.`);\n  }\n\n  useCaseRegister.set(name, useCase);\n}\n\n/**\n * Unregister a use case.\n *\n * Dropping the history namespace is best-effort: `$cleanup` is synchronous, so the\n * async cache removal is fire-and-forget with a `.catch` guard — a rejecting cache\n * driver must never turn cleanup into an unhandled rejection.\n */\nexport function $unregisterUseCase(name: string) {\n  useCaseRegister.delete(name);\n\n  Promise.resolve(cache.removeNamespace(`use-case:history:${name}`)).catch((error) => {\n    log.error(\"use-cases\", name, \"history namespace removal failed\", { error });\n  });\n}\n\n/**\n * Get a use case.\n *\n * Returns the `RegisteredUseCase` shape — including the runtime `calls` counters\n * the registry actually stores — so consumers can read call stats without an\n * ad-hoc cast.\n */\nexport function getUseCase<Output, Input>(name: string) {\n  return useCaseRegister.get(name) as RegisteredUseCase<Output, Input> | undefined;\n}\n\n/**\n * Get all use cases\n */\nexport function getUseCases() {\n  return useCaseRegister;\n}\n\n/**\n * Increase use case success calls\n */\nexport function increaseUseCaseSuccessCalls(name: string): number {\n  const useCase = useCaseRegister.get(name);\n  if (useCase) {\n    useCase.calls.success++;\n    useCase.calls.total++;\n\n    return useCase.calls.success;\n  }\n\n  return 0;\n}\n\n/**\n * Increase use case failed calls\n */\nexport function increaseUseCaseFailedCalls(name: string): number {\n  const useCase = useCaseRegister.get(name);\n  if (useCase) {\n    useCase.calls.failed++;\n    useCase.calls.total++;\n\n    return useCase.calls.failed;\n  }\n\n  return 0;\n}\n\n/**\n * Resolve the history cache TTL (seconds) from config.\n * `false` means \"use the cache driver's default\", represented as `undefined`.\n */\nfunction resolveHistoryTtl(useCaseConfig?: UseCaseConfigurations): number | undefined {\n  const ttlConfig = useCaseConfig?.history?.ttl ?? 3600; // 1 hour default\n\n  return ttlConfig === false ? undefined : ttlConfig;\n}\n\n/**\n * Get use case history from cache.\n *\n * Prunes ids whose entries have expired so the list can't accumulate dead refs.\n */\nexport async function getUseCaseHistory(name: string): Promise<UseCaseResult<any>[]> {\n  const listKey = `use-case:history:${name}:list`;\n  const ids = (await cache.get<string[]>(listKey)) || [];\n\n  const entries = await Promise.all(\n    ids.map(async (id: string) => ({\n      id,\n      result: await cache.get<UseCaseResult<any>>(`use-case:history:${name}:${id}`),\n    })),\n  );\n\n  const liveEntries = entries.filter((entry) => Boolean(entry.result));\n\n  if (liveEntries.length !== ids.length) {\n    const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n\n    await cache.set(\n      listKey,\n      liveEntries.map((entry) => entry.id),\n      resolveHistoryTtl(useCaseConfig),\n    );\n  }\n\n  return liveEntries.map((entry) => entry.result) as UseCaseResult<any>[];\n}\n\n/**\n * Add use case history to cache, capping the per-use-case list so it can't grow\n * unbounded — oldest entries (and their ids) are evicted past MAX_HISTORY_ENTRIES.\n */\nexport async function addUseCaseHistory(name: string, result: UseCaseResult<any>) {\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n\n  // On by default outside production; opt in to production with `history.enabled: true`.\n  const enabled = useCaseConfig?.history?.enabled ?? process.env.NODE_ENV !== \"production\";\n\n  if (!enabled) return;\n\n  const previous = historyWrites.get(name) ?? Promise.resolve();\n  const current = previous.catch(() => undefined).then(() => writeHistory(name, result));\n\n  historyWrites.set(name, current);\n\n  try {\n    await current;\n  } finally {\n    if (historyWrites.get(name) === current) {\n      historyWrites.delete(name);\n    }\n  }\n}\n\n/**\n * Per-use-case write chain so the list read-modify-write never interleaves\n * within a process (keeps the cap enforced under concurrency).\n */\nconst historyWrites = new Map<string, Promise<unknown>>();\n\nasync function writeHistory(name: string, result: UseCaseResult<any>) {\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n  const ttl = resolveHistoryTtl(useCaseConfig);\n  const maxEntries = useCaseConfig?.history?.maxEntries ?? 100;\n  const key = `use-case:history:${name}:${result.id}`;\n  const listKey = `use-case:history:${name}:list`;\n\n  // Store a projection only: `output` and `ctx` (tokens, payloads) never reach the cache.\n  const projection = { ...result, output: undefined, ctx: undefined } as unknown as UseCaseResult<any>;\n\n  await cache.set(key, projection, ttl);\n\n  const list = (await cache.get<string[]>(listKey)) || [];\n\n  list.push(result.id);\n\n  while (list.length > maxEntries) {\n    const evictedId = list.shift();\n\n    if (evictedId) {\n      await cache.remove(`use-case:history:${name}:${evictedId}`);\n    }\n  }\n\n  await cache.set(listKey, list, ttl);\n}\n"],"mappings":"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"}
+{"version":3,"file":"use-cases-registry.mjs","names":[],"sources":["../../../../../../../../packages/core/src/use-cases/use-cases-registry.ts"],"sourcesContent":["import { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport { config } from \"../config\";\nimport { type RegisteredUseCase, type UseCaseConfigurations, type UseCaseResult } from \"./types\";\n\n/**\n * Store registered use cases\n */\nconst useCaseRegister = new Map<string, RegisteredUseCase>();\n\n/**\n * Register a use case\n */\nexport function $registerUseCase<Output, Input>(\n  name: string,\n  useCase: RegisteredUseCase<Output, Input>,\n) {\n  if (useCaseRegister.has(name) && process.env.NODE_ENV !== \"production\") {\n    log.warn(\"use-cases\", \"registering\", `Use case \"${name}\" is already registered. Overwriting.`);\n  }\n\n  useCaseRegister.set(name, useCase);\n}\n\n/**\n * Unregister a use case.\n *\n * Dropping the history namespace is best-effort: `$cleanup` is synchronous, so the\n * async cache removal is fire-and-forget with a `.catch` guard — a rejecting cache\n * driver must never turn cleanup into an unhandled rejection.\n */\nexport function $unregisterUseCase(name: string) {\n  useCaseRegister.delete(name);\n\n  Promise.resolve(cache.removeNamespace(`use-case:history:${name}`)).catch((error) => {\n    log.error(\"use-cases\", name, \"history namespace removal failed\", { error });\n  });\n}\n\n/**\n * Get a use case.\n *\n * Returns the `RegisteredUseCase` shape — including the runtime `calls` counters\n * the registry actually stores — so consumers can read call stats without an\n * ad-hoc cast.\n */\nexport function getUseCase<Output, Input>(name: string) {\n  return useCaseRegister.get(name) as RegisteredUseCase<Output, Input> | undefined;\n}\n\n/**\n * Get all use cases\n */\nexport function getUseCases() {\n  return useCaseRegister;\n}\n\n/**\n * Increase use case success calls\n */\nexport function increaseUseCaseSuccessCalls(name: string): number {\n  const useCase = useCaseRegister.get(name);\n  if (useCase) {\n    useCase.calls.success++;\n    useCase.calls.total++;\n\n    return useCase.calls.success;\n  }\n\n  return 0;\n}\n\n/**\n * Increase use case failed calls\n */\nexport function increaseUseCaseFailedCalls(name: string): number {\n  const useCase = useCaseRegister.get(name);\n  if (useCase) {\n    useCase.calls.failed++;\n    useCase.calls.total++;\n\n    return useCase.calls.failed;\n  }\n\n  return 0;\n}\n\n/**\n * Resolve the history cache TTL (seconds) from config.\n * `false` means \"use the cache driver's default\", represented as `undefined`.\n */\nfunction resolveHistoryTtl(useCaseConfig?: UseCaseConfigurations): number | undefined {\n  const ttlConfig = useCaseConfig?.history?.ttl ?? 3600; // 1 hour default\n\n  return ttlConfig === false ? undefined : ttlConfig;\n}\n\n/**\n * Get use case history from cache.\n *\n * Prunes ids whose entries have expired so the list can't accumulate dead refs.\n */\nexport async function getUseCaseHistory(name: string): Promise<UseCaseResult<any>[]> {\n  const listKey = `use-case:history:${name}:list`;\n  const ids = (await cache.get<string[]>(listKey)) || [];\n\n  const entries = await Promise.all(\n    ids.map(async (id: string) => ({\n      id,\n      result: await cache.get<UseCaseResult<any>>(`use-case:history:${name}:${id}`),\n    })),\n  );\n\n  const liveEntries = entries.filter((entry) => Boolean(entry.result));\n\n  if (liveEntries.length !== ids.length) {\n    const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n\n    await cache.set(\n      listKey,\n      liveEntries.map((entry) => entry.id),\n      resolveHistoryTtl(useCaseConfig),\n    );\n  }\n\n  return liveEntries.map((entry) => entry.result) as UseCaseResult<any>[];\n}\n\n/**\n * Add use case history to cache, capping the per-use-case list so it can't grow\n * unbounded — oldest entries (and their ids) are evicted past MAX_HISTORY_ENTRIES.\n */\nexport async function addUseCaseHistory(name: string, result: UseCaseResult<any>) {\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n\n  // On by default outside production; opt in to production with `history.enabled: true`.\n  const enabled = useCaseConfig?.history?.enabled ?? process.env.NODE_ENV !== \"production\";\n\n  if (!enabled) return;\n\n  const previous = historyWrites.get(name) ?? Promise.resolve();\n  const current = previous.catch(() => undefined).then(() => writeHistory(name, result));\n\n  historyWrites.set(name, current);\n\n  try {\n    await current;\n  } finally {\n    if (historyWrites.get(name) === current) {\n      historyWrites.delete(name);\n    }\n  }\n}\n\n/**\n * Per-use-case write chain so the list read-modify-write never interleaves\n * within a process (keeps the cap enforced under concurrency).\n */\nconst historyWrites = new Map<string, Promise<unknown>>();\n\nasync function writeHistory(name: string, result: UseCaseResult<any>) {\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\");\n  const ttl = resolveHistoryTtl(useCaseConfig);\n  const maxEntries = useCaseConfig?.history?.maxEntries ?? 100;\n  const key = `use-case:history:${name}:${result.id}`;\n  const listKey = `use-case:history:${name}:list`;\n\n  // Store a projection only: `output` and `ctx` (tokens, payloads) never reach the cache.\n  const projection = {\n    ...result,\n    output: undefined,\n    ctx: undefined,\n  } as unknown as UseCaseResult<any>;\n\n  await cache.set(key, projection, ttl);\n\n  const list = (await cache.get<string[]>(listKey)) || [];\n\n  list.push(result.id);\n\n  while (list.length > maxEntries) {\n    const evictedId = list.shift();\n\n    if (evictedId) {\n      await cache.remove(`use-case:history:${name}:${evictedId}`);\n    }\n  }\n\n  await cache.set(listKey, list, ttl);\n}\n"],"mappings":"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"}

package/esm/utils/clock.d.mts

@@ -0,0 +1,33 @@
+//#region ../../packages/core/src/utils/clock.d.ts
+/**
+ * The application clock.
+ *
+ * Read the current time through `clock` instead of `new Date()` / `Date.now()`
+ * where a test needs to control it: tokens that expire, "created 5 minutes
+ * ago", scheduled cut-offs. In the test environment the test kit swaps the
+ * source for a frozen one (`clockFake` from `@warlock.js/core/tests`); in
+ * every other environment it is the system clock.
+ *
+ * Only code that reads `clock` is affected — the global `Date` and timers are
+ * never patched, so a fake clock cannot stall `setTimeout` or a driver.
+ *
+ * @example
+ * import { clock } from "@warlock.js/core";
+ *
+ * const expiresAt = new Date(clock.timestamp() + 15 * 60_000);
+ */
+type ClockSource = {
+  /** Milliseconds since the Unix epoch. */now(): number;
+};
+declare const clock: {
+  /** The current time as a `Date`. */now(): Date; /** The current time in milliseconds since the Unix epoch. */
+  timestamp(): number;
+};
+/**
+ * Replace the clock's source, or restore the system clock with `undefined`.
+ * The test kit's `clockFake` is built on this.
+ */
+declare function setClockSource(next: ClockSource | undefined): void;
+//#endregion
+export { ClockSource, clock, setClockSource };
+//# sourceMappingURL=clock.d.mts.map

package/esm/utils/clock.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/utils/clock.ts"],"mappings":";;AAiBA;;;;AAEK;AAeL;;;;;;;;;AAgBA;;KAjCY,WAAA;EAiCyB,yCA/BnC,GAAG;AAAA;AAAA,cAeQ,KAAA;6CAEJ,IAAI;;;;;;;iBAcG,cAAA,CAAe,IAA6B,EAAvB,WAAW"}

package/esm/utils/clock.mjs

@@ -0,0 +1,27 @@
+//#region ../../packages/core/src/utils/clock.ts
+const systemClock = { now: () => Date.now() };
+const SOURCE_KEY = Symbol.for("warlock.core.clockSource");
+function source() {
+	return globalThis[SOURCE_KEY] ?? systemClock;
+}
+const clock = {
+	/** The current time as a `Date`. */
+	now() {
+		return new Date(source().now());
+	},
+	/** The current time in milliseconds since the Unix epoch. */
+	timestamp() {
+		return source().now();
+	}
+};
+/**
+* Replace the clock's source, or restore the system clock with `undefined`.
+* The test kit's `clockFake` is built on this.
+*/
+function setClockSource(next) {
+	globalThis[SOURCE_KEY] = next;
+}
+
+//#endregion
+export { clock, setClockSource };
+//# sourceMappingURL=clock.mjs.map

package/esm/utils/clock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.mjs","names":[],"sources":["../../../../../../../../packages/core/src/utils/clock.ts"],"sourcesContent":["/**\n * The application clock.\n *\n * Read the current time through `clock` instead of `new Date()` / `Date.now()`\n * where a test needs to control it: tokens that expire, \"created 5 minutes\n * ago\", scheduled cut-offs. In the test environment the test kit swaps the\n * source for a frozen one (`clockFake` from `@warlock.js/core/tests`); in\n * every other environment it is the system clock.\n *\n * Only code that reads `clock` is affected — the global `Date` and timers are\n * never patched, so a fake clock cannot stall `setTimeout` or a driver.\n *\n * @example\n * import { clock } from \"@warlock.js/core\";\n *\n * const expiresAt = new Date(clock.timestamp() + 15 * 60_000);\n */\nexport type ClockSource = {\n  /** Milliseconds since the Unix epoch. */\n  now(): number;\n};\n\nconst systemClock: ClockSource = { now: () => Date.now() };\n\n// On `globalThis` so the framework loaded twice in one Vitest worker (native\n// and through vite-node) still reads one source.\nconst SOURCE_KEY = Symbol.for(\"warlock.core.clockSource\");\n\ntype SourceHolder = { [SOURCE_KEY]?: ClockSource };\n\nfunction source(): ClockSource {\n  return (globalThis as SourceHolder)[SOURCE_KEY] ?? systemClock;\n}\n\nexport const clock = {\n  /** The current time as a `Date`. */\n  now(): Date {\n    return new Date(source().now());\n  },\n\n  /** The current time in milliseconds since the Unix epoch. */\n  timestamp(): number {\n    return source().now();\n  },\n};\n\n/**\n * Replace the clock's source, or restore the system clock with `undefined`.\n * The test kit's `clockFake` is built on this.\n */\nexport function setClockSource(next: ClockSource | undefined): void {\n  (globalThis as SourceHolder)[SOURCE_KEY] = next;\n}\n"],"mappings":";AAsBA,MAAM,cAA2B,EAAE,WAAW,KAAK,IAAI,EAAE;AAIzD,MAAM,aAAa,OAAO,IAAI,0BAA0B;AAIxD,SAAS,SAAsB;CAC7B,OAAQ,WAA4B,eAAe;AACrD;AAEA,MAAa,QAAQ;;CAEnB,MAAY;EACV,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC;CAChC;;CAGA,YAAoB;EAClB,OAAO,OAAO,CAAC,CAAC,IAAI;CACtB;AACF;;;;;AAMA,SAAgB,eAAe,MAAqC;CAClE,AAAC,WAA4B,cAAc;AAC7C"}

package/esm/utils/framework-vesion.mjs

@@ -11,7 +11,7 @@ let cachedVersion = null;
 */
 async function getWarlockVersion() {
 	if (cachedVersion) return cachedVersion;
-	const version = (await getJsonFileAsync(path.join(import.meta.dirname, "./../../package.json"))).version.replace(/\^|\~/g, "");
+	const version = (await getJsonFileAsync(path.join(import.meta.dirname, "./../../package.json"))).version.replace(/\^|~/g, "");
 	cachedVersion = version;
 	return version;
 }

package/esm/utils/framework-vesion.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"framework-vesion.mjs","names":[],"sources":["../../../../../../../../packages/core/src/utils/framework-vesion.ts"],"sourcesContent":["import { getJsonFileAsync } from \"@warlock.js/fs\";\nimport path from \"node:path\";\n\n/**\n * Cached version string\n */\nlet cachedVersion: string | null = null;\n\n/**\n * Get the framework version from package.json (cached)\n */\nexport async function getWarlockVersion(): Promise<string> {\n  if (cachedVersion) return cachedVersion;\n\n  const frameworkPackageJson = (await getJsonFileAsync(\n    path.join(import.meta.dirname, \"./../../package.json\"),\n  )) as { version: string };\n\n  const version = frameworkPackageJson.version.replace(/\\^|\\~/g, \"\");\n  cachedVersion = version;\n  return version;\n}\n\nexport function getFrameworkVersion(): string | null {\n  return cachedVersion;\n}\n"],"mappings":";;;;;;;AAMA,IAAI,gBAA+B;;;;AAKnC,eAAsB,oBAAqC;CACzD,IAAI,eAAe,OAAO;CAM1B,MAAM,WAAU,MAJoB,iBAClC,KAAK,KAAK,OAAO,KAAK,SAAS,sBAAsB,CACvD,EAEoC,CAAC,QAAQ,QAAQ,UAAU,EAAE;CACjE,gBAAgB;CAChB,OAAO;AACT;AAEA,SAAgB,sBAAqC;CACnD,OAAO;AACT"}
+{"version":3,"file":"framework-vesion.mjs","names":[],"sources":["../../../../../../../../packages/core/src/utils/framework-vesion.ts"],"sourcesContent":["import { getJsonFileAsync } from \"@warlock.js/fs\";\nimport path from \"node:path\";\n\n/**\n * Cached version string\n */\nlet cachedVersion: string | null = null;\n\n/**\n * Get the framework version from package.json (cached)\n */\nexport async function getWarlockVersion(): Promise<string> {\n  if (cachedVersion) return cachedVersion;\n\n  const frameworkPackageJson = (await getJsonFileAsync(\n    path.join(import.meta.dirname, \"./../../package.json\"),\n  )) as { version: string };\n\n  const version = frameworkPackageJson.version.replace(/\\^|~/g, \"\");\n  cachedVersion = version;\n  return version;\n}\n\nexport function getFrameworkVersion(): string | null {\n  return cachedVersion;\n}\n"],"mappings":";;;;;;;AAMA,IAAI,gBAA+B;;;;AAKnC,eAAsB,oBAAqC;CACzD,IAAI,eAAe,OAAO;CAM1B,MAAM,WAAU,MAJoB,iBAClC,KAAK,KAAK,OAAO,KAAK,SAAS,sBAAsB,CACvD,EAEoC,CAAC,QAAQ,QAAQ,SAAS,EAAE;CAChE,gBAAgB;CAChB,OAAO;AACT;AAEA,SAAgB,sBAAqC;CACnD,OAAO;AACT"}

package/esm/utils/ids.d.mts

@@ -0,0 +1,32 @@
+//#region ../../packages/core/src/utils/ids.d.ts
+/**
+ * Identifier generation the test kit can make deterministic.
+ *
+ * Generate ids through `ids` instead of calling `crypto.randomUUID()` directly
+ * where a test needs to predict them (a snapshot, a file name, a link). In the
+ * test environment `idsFake` from `@warlock.js/core/tests` replaces the source
+ * with a numbered sequence; in every other environment the values come from
+ * `node:crypto`.
+ *
+ * @example
+ * import { ids } from "@warlock.js/core";
+ *
+ * const reference = ids.uuid();
+ * const resetToken = ids.token(48);
+ */
+type IdsSource = {
+  /** A version 4 UUID. */uuid(): string; /** A URL-safe random string of exactly `length` characters. */
+  token(length: number): string;
+};
+declare const ids: {
+  /** A version 4 UUID. */uuid(): string; /** A URL-safe random string, 32 characters unless `length` says otherwise. */
+  token(length?: number): string;
+};
+/**
+ * Replace the id source, or restore `node:crypto` with `undefined`.
+ * The test kit's `idsFake` is built on this.
+ */
+declare function setIdsSource(next: IdsSource | undefined): void;
+//#endregion
+export { IdsSource, ids, setIdsSource };
+//# sourceMappingURL=ids.d.mts.map

package/esm/utils/ids.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/utils/ids.ts"],"mappings":";;AAiBA;;;;;;;;AAIsB;AAmBtB;;;;;KAvBY,SAAA;0BAEV,IAAA;EAEA,KAAA,CAAM,MAAA;AAAA;AAAA,cAmBK,GAAA;EAoBsB;;;;;;;iBAAnB,YAAA,CAAa,IAA2B,EAArB,SAAS"}

package/esm/utils/ids.mjs

@@ -0,0 +1,33 @@
+import { randomBytes, randomUUID } from "node:crypto";
+
+//#region ../../packages/core/src/utils/ids.ts
+const cryptoIds = {
+	uuid: () => randomUUID(),
+	token: (length) => randomBytes(Math.ceil(length * 3 / 4) + 1).toString("base64url").slice(0, length)
+};
+const SOURCE_KEY = Symbol.for("warlock.core.idsSource");
+function source() {
+	return globalThis[SOURCE_KEY] ?? cryptoIds;
+}
+const ids = {
+	/** A version 4 UUID. */
+	uuid() {
+		return source().uuid();
+	},
+	/** A URL-safe random string, 32 characters unless `length` says otherwise. */
+	token(length = 32) {
+		if (!Number.isInteger(length) || length < 1) throw new RangeError(`ids.token(length) needs a positive integer, got ${String(length)}.`);
+		return source().token(length);
+	}
+};
+/**
+* Replace the id source, or restore `node:crypto` with `undefined`.
+* The test kit's `idsFake` is built on this.
+*/
+function setIdsSource(next) {
+	globalThis[SOURCE_KEY] = next;
+}
+
+//#endregion
+export { ids, setIdsSource };
+//# sourceMappingURL=ids.mjs.map

package/esm/utils/ids.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.mjs","names":[],"sources":["../../../../../../../../packages/core/src/utils/ids.ts"],"sourcesContent":["import { randomBytes, randomUUID } from \"node:crypto\";\n\n/**\n * Identifier generation the test kit can make deterministic.\n *\n * Generate ids through `ids` instead of calling `crypto.randomUUID()` directly\n * where a test needs to predict them (a snapshot, a file name, a link). In the\n * test environment `idsFake` from `@warlock.js/core/tests` replaces the source\n * with a numbered sequence; in every other environment the values come from\n * `node:crypto`.\n *\n * @example\n * import { ids } from \"@warlock.js/core\";\n *\n * const reference = ids.uuid();\n * const resetToken = ids.token(48);\n */\nexport type IdsSource = {\n  /** A version 4 UUID. */\n  uuid(): string;\n  /** A URL-safe random string of exactly `length` characters. */\n  token(length: number): string;\n};\n\nconst cryptoIds: IdsSource = {\n  uuid: () => randomUUID(),\n  token: (length) =>\n    randomBytes(Math.ceil((length * 3) / 4) + 1)\n      .toString(\"base64url\")\n      .slice(0, length),\n};\n\nconst SOURCE_KEY = Symbol.for(\"warlock.core.idsSource\");\n\ntype SourceHolder = { [SOURCE_KEY]?: IdsSource };\n\nfunction source(): IdsSource {\n  return (globalThis as SourceHolder)[SOURCE_KEY] ?? cryptoIds;\n}\n\nexport const ids = {\n  /** A version 4 UUID. */\n  uuid(): string {\n    return source().uuid();\n  },\n\n  /** A URL-safe random string, 32 characters unless `length` says otherwise. */\n  token(length = 32): string {\n    if (!Number.isInteger(length) || length < 1) {\n      throw new RangeError(`ids.token(length) needs a positive integer, got ${String(length)}.`);\n    }\n\n    return source().token(length);\n  },\n};\n\n/**\n * Replace the id source, or restore `node:crypto` with `undefined`.\n * The test kit's `idsFake` is built on this.\n */\nexport function setIdsSource(next: IdsSource | undefined): void {\n  (globalThis as SourceHolder)[SOURCE_KEY] = next;\n}\n"],"mappings":";;;AAwBA,MAAM,YAAuB;CAC3B,YAAY,WAAW;CACvB,QAAQ,WACN,YAAY,KAAK,KAAM,SAAS,IAAK,CAAC,IAAI,CAAC,CAAC,CACzC,SAAS,WAAW,CAAC,CACrB,MAAM,GAAG,MAAM;AACtB;AAEA,MAAM,aAAa,OAAO,IAAI,wBAAwB;AAItD,SAAS,SAAoB;CAC3B,OAAQ,WAA4B,eAAe;AACrD;AAEA,MAAa,MAAM;;CAEjB,OAAe;EACb,OAAO,OAAO,CAAC,CAAC,KAAK;CACvB;;CAGA,MAAM,SAAS,IAAY;EACzB,IAAI,CAAC,OAAO,UAAU,MAAM,KAAK,SAAS,GACxC,MAAM,IAAI,WAAW,mDAAmD,OAAO,MAAM,EAAE,EAAE;EAG3F,OAAO,OAAO,CAAC,CAAC,MAAM,MAAM;CAC9B;AACF;;;;;AAMA,SAAgB,aAAa,MAAmC;CAC9D,AAAC,WAA4B,cAAc;AAC7C"}

package/esm/utils/index.d.mts

@@ -1,12 +1,15 @@
 import { LocalizedObject, getLocalized } from "./get-localized.mjs";
 import { Environment, RuntimeStrategy, environment, setEnvironment } from "./environment.mjs";
 import { appLog } from "./app-log.mjs";
+import { ClockSource, clock, setClockSource } from "./clock.mjs";
 import { DatabaseLog, DatabaseLogOptions } from "./database-log.mjs";
+import { IdsSource, ids, setIdsSource } from "./ids.mjs";
 import { Path } from "./normalized-path.mjs";
 import { fetchLatestVersion } from "./npm-registry.mjs";
 import { appPath, cachePath, configPath, logsPath, paths, publicPath, rootPath, sanitizePath, srcPath, storagePath, tempPath, uploadsPath, warlockPath } from "./paths.mjs";
 import { promiseAllObject } from "./promise-all-object.mjs";
 import { Queue } from "./queue.mjs";
+import { JavaScriptRuntime, JavaScriptRuntimeName, SUPPORTED_RUNTIMES_DOCS_URL, assertNodeOnlyCommand, describeJavaScriptRuntime, detectJavaScriptRuntime, nodeOnlyCommandError, unverifiedBuildRuntimeNotice } from "./runtime.mjs";
 import { sleep } from "./sleep.mjs";
 import { sluggable } from "./sluggable.mjs";
 import { toJson } from "./to-json.mjs";

package/esm/utils/index.mjs

@@ -1,12 +1,15 @@
 import { appLog } from "./app-log.mjs";
+import { clock, setClockSource } from "./clock.mjs";
 import { DatabaseLog } from "./database-log.mjs";
 import { environment, setEnvironment } from "./environment.mjs";
 import { getLocalized } from "./get-localized.mjs";
+import { ids, setIdsSource } from "./ids.mjs";
 import { Path } from "./normalized-path.mjs";
 import { fetchLatestVersion } from "./npm-registry.mjs";
 import { appPath, cachePath, configPath, logsPath, paths, publicPath, rootPath, sanitizePath, srcPath, storagePath, tempPath, uploadsPath, warlockPath } from "./paths.mjs";
 import { promiseAllObject } from "./promise-all-object.mjs";
 import { Queue } from "./queue.mjs";
+import { SUPPORTED_RUNTIMES_DOCS_URL, assertNodeOnlyCommand, describeJavaScriptRuntime, detectJavaScriptRuntime, nodeOnlyCommandError, unverifiedBuildRuntimeNotice } from "./runtime.mjs";
 import { sleep } from "./sleep.mjs";
 import { sluggable } from "./sluggable.mjs";
 import { toJson } from "./to-json.mjs";