@zodmire/cli 0.1.2 → 0.1.3

package/mod.mjs

@@ -2,8 +2,9 @@ import { register } from "node:module";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { VENDORED_FILE_MANIFEST, buildCompositionArtifacts, buildContextNormalizedSpecFromConfig, buildFileArtifactTags, buildNormalizedCompositionSpec, buildNormalizedSpecTags, buildV5ContextArtifacts, filterPerContextArtifactsForComposition, generateContextArtifacts, inferReconcileScopes, mergeGeneratedArtifacts, prepareAllVendoredFiles, resolveAbsoluteContextInputs, serializeCompositionSpec, serializeContextSpec } from "@zodmire/core";
-import { materializeOwnedArtifacts } from "@zodmire/core/materialize";
+import { VENDORED_FILE_MANIFEST, buildCompositionArtifacts, buildContextNormalizedSpecFromConfig, buildFileArtifactTags, buildNormalizedCompositionSpec, buildNormalizedSpecTags, buildV5ContextArtifacts, ensureContextSupportFilesExist, filterPerContextArtifactsForComposition, generateContextArtifacts, inferReconcileScopes, mergeGeneratedArtifacts, prepareAllVendoredFiles, resolveAbsoluteContextInputs, resolveArtifactOwnership, serializeCompositionSpec, serializeContextSpec, validateContextImports } from "@zodmire/core";
+import { MaterializationManifestSchema, getPersistedMaterializationManifestPath, materializeOwnedArtifacts } from "@zodmire/core/materialize";
+import { CompositionConfigSchema } from "@zodmire/config";
 import { statSync } from "node:fs";
 import { spawn } from "node:child_process";
 
@@ -109,10 +110,10 @@ async function mirrorToSwampDataLayer(opts) {
 //#region packages/cli/generate.ts
 async function runGenerate(opts) {
 	const configPath = opts.configPath.startsWith("/") ? opts.configPath : `${process.cwd()}/${opts.configPath}`;
-	if (opts.composition) await runCompositionGenerate(configPath, opts.targetOverride, opts.versionData);
-	else await runContextGenerate(configPath, opts.targetOverride, opts.versionData);
+	if (opts.composition) await runCompositionGenerate(configPath, opts.targetOverride, opts.versionData, opts.dryRun);
+	else await runContextGenerate(configPath, opts.targetOverride, opts.versionData, opts.dryRun);
 }
-async function runContextGenerate(configPath, targetOverride, versionData) {
+async function runContextGenerate(configPath, targetOverride, versionData, dryRun) {
 	const resolvedInputs = await resolveAbsoluteContextInputs(configPath);
 	const config = resolvedInputs.config;
 	const codegenSupportPath = resolvedInputs.codegenSupportPath;
@@ -120,13 +121,21 @@ async function runContextGenerate(configPath, targetOverride, versionData) {
 	console.log(`  codegen support: ${codegenSupportPath}`);
 	const artifacts = await buildV5ContextArtifacts({
 		contextConfigPath: configPath,
-		codegenSupportPath
+		codegenSupportPath,
+		generation: config.generation
 	});
 	const targetRoot = targetOverride ?? config.materialization?.targetRoot;
 	if (!targetRoot) throw new Error("No --target specified and context config has no materialization.targetRoot");
 	const resolvedTarget = targetRoot.startsWith("/") ? targetRoot : `${process.cwd()}/${targetRoot}`;
 	console.log(`  target: ${resolvedTarget}`);
-	const result = await materializeOwnedArtifacts(resolvedTarget, artifacts, GENERATOR_VERSION, { reconcileScopes: inferReconcileScopes(artifacts) });
+	const result = await materializeOwnedArtifacts(resolvedTarget, artifacts, GENERATOR_VERSION, {
+		reconcileScopes: inferReconcileScopes(artifacts),
+		dryRun
+	});
+	if (dryRun) {
+		printDryRunSummary(resolvedTarget, result);
+		return;
+	}
 	if (versionData) {
 		if (!isSwampRepoAvailable()) throw new Error("Swamp repo not initialized. Run `swamp init` or omit --version-data");
 		const contextSpec = await buildContextNormalizedSpecFromConfig({
@@ -159,12 +168,27 @@ async function runContextGenerate(configPath, targetOverride, versionData) {
 	}
 	console.log(`\nMaterialized ${result.files.length} files to ${result.targetRoot}`);
 }
-async function runCompositionGenerate(compositionConfigPath, targetOverride, versionData) {
-	const compositionConfig = (await import(new URL(compositionConfigPath, "file:///").href)).default;
+function printDryRunSummary(target, result) {
+	const counts = {
+		write: 0,
+		overwrite: 0,
+		conflict: 0,
+		skip: 0,
+		delete: 0
+	};
+	for (const file of result.files) counts[file.action] = (counts[file.action] ?? 0) + 1;
+	console.log(`\nDry run for ${target}:`);
+	console.log(`  write:     ${counts.write} files`);
+	console.log(`  overwrite: ${counts.overwrite} files`);
+	console.log(`  delete:    ${counts.delete} files`);
+	console.log(`  skip:      ${counts.skip} files`);
+}
+async function runCompositionGenerate(compositionConfigPath, targetOverride, versionData, dryRun) {
+	const configModule = await import(new URL(compositionConfigPath, "file:///").href);
+	const compositionConfig = CompositionConfigSchema.parse(configModule.default);
 	const targetRoot = targetOverride ?? compositionConfig.materialization?.targetRoot;
 	if (!targetRoot) throw new Error("No --target specified and composition config has no materialization.targetRoot");
 	const resolvedTarget = targetRoot.startsWith("/") ? targetRoot : `${process.cwd()}/${targetRoot}`;
-	if (!compositionConfig.contextConfigs || compositionConfig.contextConfigs.length === 0) throw new Error("Composition config must include contextConfigs array with { contextConfigPath, codegenSupportPath } entries");
 	const compositionDir = compositionConfigPath.substring(0, compositionConfigPath.lastIndexOf("/") + 1);
 	const resolvedContextConfigs = compositionConfig.contextConfigs.map((cfg) => ({
 		contextConfigPath: cfg.contextConfigPath.startsWith("/") ? cfg.contextConfigPath : compositionDir + cfg.contextConfigPath.replace(/^\.\//, ""),
@@ -178,7 +202,14 @@ async function runCompositionGenerate(compositionConfigPath, targetOverride, ver
 	const compositionArtifacts = await buildCompositionArtifacts(compositionConfigPath, contextSpecs);
 	const allArtifacts = mergeGeneratedArtifacts(...perContextArtifacts.map(filterPerContextArtifactsForComposition), compositionArtifacts).sort((a, b) => a.logicalPath.localeCompare(b.logicalPath));
 	console.log(`  target: ${resolvedTarget}`);
-	const result = await materializeOwnedArtifacts(resolvedTarget, allArtifacts, GENERATOR_VERSION, { reconcileScopes: inferReconcileScopes(allArtifacts) });
+	const result = await materializeOwnedArtifacts(resolvedTarget, allArtifacts, GENERATOR_VERSION, {
+		reconcileScopes: inferReconcileScopes(allArtifacts),
+		dryRun
+	});
+	if (dryRun) {
+		printDryRunSummary(resolvedTarget, result);
+		return;
+	}
 	if (versionData) {
 		if (!isSwampRepoAvailable()) throw new Error("Swamp repo not initialized. Run `swamp init` or omit --version-data");
 		const specJson = serializeCompositionSpec(compositionSpec, GENERATOR_VERSION);
@@ -208,6 +239,211 @@ async function runCompositionGenerate(compositionConfigPath, targetOverride, ver
 	console.log(`\nMaterialized ${result.files.length} files to ${result.targetRoot}`);
 }
 
+//#endregion
+//#region packages/cli/validate.ts
+async function runCheck(name, fn) {
+	try {
+		await fn();
+		return {
+			name,
+			pass: true
+		};
+	} catch (error) {
+		return {
+			name,
+			pass: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+async function runValidate(opts) {
+	const configPath = opts.configPath.startsWith("/") ? opts.configPath : `${process.cwd()}/${opts.configPath}`;
+	const results = [];
+	if (opts.composition) {
+		results.push(await runCheck("composition-config-import", async () => {
+			const configModule = await import(new URL(configPath, "file:///").href);
+			CompositionConfigSchema.parse(configModule.default);
+		}));
+		results.push(await runCheck("composition-context-configs", async () => {
+			const configModule = await import(new URL(configPath, "file:///").href);
+			const compositionConfig = CompositionConfigSchema.parse(configModule.default);
+			const compositionDir = configPath.substring(0, configPath.lastIndexOf("/") + 1);
+			for (const cfg of compositionConfig.contextConfigs) {
+				const contextConfigPath = cfg.contextConfigPath.startsWith("/") ? cfg.contextConfigPath : compositionDir + cfg.contextConfigPath.replace(/^\.\//, "");
+				const codegenSupportPath = cfg.codegenSupportPath.startsWith("/") ? cfg.codegenSupportPath : compositionDir + cfg.codegenSupportPath.replace(/^\.\//, "");
+				const resolved = await resolveAbsoluteContextInputs(contextConfigPath);
+				await ensureContextSupportFilesExist(resolved);
+				await validateContextImports({
+					...resolved,
+					codegenSupportPath
+				});
+			}
+		}));
+	} else {
+		results.push(await runCheck("context-inputs-resolve", async () => {
+			await resolveAbsoluteContextInputs(configPath);
+		}));
+		results.push(await runCheck("schema-files-exist", async () => {
+			await ensureContextSupportFilesExist(await resolveAbsoluteContextInputs(configPath));
+		}));
+		results.push(await runCheck("schema-imports-parse", async () => {
+			await validateContextImports(await resolveAbsoluteContextInputs(configPath));
+		}));
+	}
+	let hasFailure = false;
+	for (const result of results) {
+		const icon = result.pass ? "✓" : "✗";
+		console.log(`  ${icon} ${result.name}`);
+		if (!result.pass && result.error) {
+			console.log(`    ${result.error}`);
+			hasFailure = true;
+		}
+	}
+	if (hasFailure) {
+		console.log("\nValidation failed.");
+		process.exit(1);
+	} else console.log("\nAll checks passed.");
+}
+
+//#endregion
+//#region packages/cli/inspect.ts
+async function runInspect(opts) {
+	const configPath = opts.configPath.startsWith("/") ? opts.configPath : `${process.cwd()}/${opts.configPath}`;
+	if (opts.composition) await runCompositionInspect(configPath);
+	else await runContextInspect(configPath);
+}
+async function runContextInspect(configPath) {
+	const codegenSupportPath = (await resolveAbsoluteContextInputs(configPath)).codegenSupportPath;
+	const json = serializeContextSpec(await buildContextNormalizedSpecFromConfig({
+		contextConfigPath: configPath,
+		codegenSupportPath
+	}), GENERATOR_VERSION);
+	console.log(json);
+}
+async function runCompositionInspect(compositionConfigPath) {
+	const configModule = await import(new URL(compositionConfigPath, "file:///").href);
+	const compositionConfig = CompositionConfigSchema.parse(configModule.default);
+	const compositionDir = compositionConfigPath.substring(0, compositionConfigPath.lastIndexOf("/") + 1);
+	const resolvedContextConfigs = compositionConfig.contextConfigs.map((cfg) => ({
+		contextConfigPath: cfg.contextConfigPath.startsWith("/") ? cfg.contextConfigPath : compositionDir + cfg.contextConfigPath.replace(/^\.\//, ""),
+		codegenSupportPath: cfg.codegenSupportPath.startsWith("/") ? cfg.codegenSupportPath : compositionDir + cfg.codegenSupportPath.replace(/^\.\//, "")
+	}));
+	const json = serializeCompositionSpec(buildNormalizedCompositionSpec(compositionConfig, await Promise.all(resolvedContextConfigs.map((cfg) => buildContextNormalizedSpecFromConfig(cfg)))), GENERATOR_VERSION);
+	console.log(json);
+}
+
+//#endregion
+//#region packages/cli/plan_cmd.ts
+async function runPlan(opts) {
+	const configPath = opts.configPath.startsWith("/") ? opts.configPath : `${process.cwd()}/${opts.configPath}`;
+	if (opts.composition) await runCompositionPlan(configPath);
+	else await runContextPlan(configPath);
+}
+async function runContextPlan(configPath) {
+	const codegenSupportPath = (await resolveAbsoluteContextInputs(configPath)).codegenSupportPath;
+	printPlan(configPath, await buildV5ContextArtifacts({
+		contextConfigPath: configPath,
+		codegenSupportPath
+	}));
+}
+async function runCompositionPlan(compositionConfigPath) {
+	const configModule = await import(new URL(compositionConfigPath, "file:///").href);
+	const compositionConfig = CompositionConfigSchema.parse(configModule.default);
+	const compositionDir = compositionConfigPath.substring(0, compositionConfigPath.lastIndexOf("/") + 1);
+	const resolvedContextConfigs = compositionConfig.contextConfigs.map((cfg) => ({
+		contextConfigPath: cfg.contextConfigPath.startsWith("/") ? cfg.contextConfigPath : compositionDir + cfg.contextConfigPath.replace(/^\.\//, ""),
+		codegenSupportPath: cfg.codegenSupportPath.startsWith("/") ? cfg.codegenSupportPath : compositionDir + cfg.codegenSupportPath.replace(/^\.\//, "")
+	}));
+	const contextSpecs = await Promise.all(resolvedContextConfigs.map((cfg) => buildContextNormalizedSpecFromConfig(cfg)));
+	const compositionSpec = buildNormalizedCompositionSpec(compositionConfig, contextSpecs);
+	const perContextArtifacts = contextSpecs.map((contextSpec) => generateContextArtifacts(contextSpec, { infrastructureStrategy: compositionSpec.infrastructure }));
+	const compositionArtifacts = await buildCompositionArtifacts(compositionConfigPath, contextSpecs);
+	printPlan(compositionConfigPath, mergeGeneratedArtifacts(...perContextArtifacts.map(filterPerContextArtifactsForComposition), compositionArtifacts).sort((a, b) => a.logicalPath.localeCompare(b.logicalPath)));
+}
+function printPlan(configPath, artifacts) {
+	console.log(`Plan for ${configPath}:`);
+	for (const artifact of artifacts) {
+		const label = `[${resolveArtifactOwnership(artifact).ownershipScope}]`;
+		console.log(`  ${label.padEnd(16)} ${artifact.logicalPath}`);
+	}
+	console.log(`\n${artifacts.length} artifacts would be generated.`);
+}
+
+//#endregion
+//#region packages/cli/diff.ts
+async function runDiff(opts) {
+	const configPath = opts.configPath.startsWith("/") ? opts.configPath : `${process.cwd()}/${opts.configPath}`;
+	if (opts.composition) await runCompositionDiff(configPath, opts.targetOverride);
+	else await runContextDiff(configPath, opts.targetOverride);
+}
+async function runContextDiff(configPath, targetOverride) {
+	const resolvedInputs = await resolveAbsoluteContextInputs(configPath);
+	const config = resolvedInputs.config;
+	const codegenSupportPath = resolvedInputs.codegenSupportPath;
+	const artifacts = await buildV5ContextArtifacts({
+		contextConfigPath: configPath,
+		codegenSupportPath
+	});
+	const targetRoot = targetOverride ?? config.materialization?.targetRoot;
+	if (!targetRoot) throw new Error("No --target specified and context config has no materialization.targetRoot");
+	printDiff(targetRoot.startsWith("/") ? targetRoot : `${process.cwd()}/${targetRoot}`, artifacts);
+}
+async function runCompositionDiff(compositionConfigPath, targetOverride) {
+	const configModule = await import(new URL(compositionConfigPath, "file:///").href);
+	const compositionConfig = CompositionConfigSchema.parse(configModule.default);
+	const targetRoot = targetOverride ?? compositionConfig.materialization?.targetRoot;
+	if (!targetRoot) throw new Error("No --target specified and composition config has no materialization.targetRoot");
+	const resolvedTarget = targetRoot.startsWith("/") ? targetRoot : `${process.cwd()}/${targetRoot}`;
+	const compositionDir = compositionConfigPath.substring(0, compositionConfigPath.lastIndexOf("/") + 1);
+	const resolvedContextConfigs = compositionConfig.contextConfigs.map((cfg) => ({
+		contextConfigPath: cfg.contextConfigPath.startsWith("/") ? cfg.contextConfigPath : compositionDir + cfg.contextConfigPath.replace(/^\.\//, ""),
+		codegenSupportPath: cfg.codegenSupportPath.startsWith("/") ? cfg.codegenSupportPath : compositionDir + cfg.codegenSupportPath.replace(/^\.\//, "")
+	}));
+	const contextSpecs = await Promise.all(resolvedContextConfigs.map((cfg) => buildContextNormalizedSpecFromConfig(cfg)));
+	const compositionSpec = buildNormalizedCompositionSpec(compositionConfig, contextSpecs);
+	const perContextArtifacts = contextSpecs.map((contextSpec) => generateContextArtifacts(contextSpec, { infrastructureStrategy: compositionSpec.infrastructure }));
+	const compositionArtifacts = await buildCompositionArtifacts(compositionConfigPath, contextSpecs);
+	printDiff(resolvedTarget, mergeGeneratedArtifacts(...perContextArtifacts.map(filterPerContextArtifactsForComposition), compositionArtifacts).sort((a, b) => a.logicalPath.localeCompare(b.logicalPath)));
+}
+async function printDiff(targetRoot, artifacts) {
+	const manifestPath = getPersistedMaterializationManifestPath(targetRoot);
+	let manifestEntries;
+	try {
+		const manifestText = await readFile(manifestPath, "utf-8");
+		const manifest = MaterializationManifestSchema.parse(JSON.parse(manifestText));
+		manifestEntries = new Set(manifest.files.map((f) => f.logicalPath));
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			console.log(`No existing manifest found at ${manifestPath}`);
+			console.log(`All ${artifacts.length} artifacts would be new.\n`);
+			for (const artifact of artifacts) console.log(`  + ${artifact.logicalPath}`);
+			return;
+		}
+		throw error;
+	}
+	const plannedPaths = new Set(artifacts.map((a) => a.logicalPath));
+	const added = [];
+	const removed = [];
+	const unchanged = [];
+	for (const artifact of artifacts) if (manifestEntries.has(artifact.logicalPath)) unchanged.push(artifact.logicalPath);
+	else added.push(artifact.logicalPath);
+	for (const existingPath of manifestEntries) if (!plannedPaths.has(existingPath)) removed.push(existingPath);
+	console.log(`Diff against ${manifestPath}:\n`);
+	if (added.length > 0) {
+		console.log(`  Added (${added.length}):`);
+		for (const path of added) console.log(`    + ${path}`);
+	}
+	if (removed.length > 0) {
+		console.log(`  Removed (${removed.length}):`);
+		for (const path of removed) console.log(`    - ${path}`);
+	}
+	if (unchanged.length > 0) {
+		console.log(`  Unchanged (${unchanged.length}):`);
+		for (const path of unchanged) console.log(`    = ${path}`);
+	}
+	console.log(`\nSummary: ${added.length} added, ${removed.length} removed, ${unchanged.length} unchanged`);
+}
+
 //#endregion
 //#region packages/cli/mod.ts
 register(`data:text/javascript,${encodeURIComponent(`
@@ -226,20 +462,29 @@ function printUsage() {
 
 Usage:
   zodmire init --target <dir>
-  zodmire generate --config <path> [--composition] [--target <dir>] [--version-data]
+  zodmire generate --config <path> [--composition] [--target <dir>] [--version-data] [--dry-run]
+  zodmire validate --config <path> [--composition]
+  zodmire inspect-spec --config <path> [--composition]
+  zodmire plan --config <path> [--composition] [--target <dir>]
+  zodmire diff --config <path> [--composition] [--target <dir>]
   zodmire --version
   zodmire --help
 
 Commands:
-  init        Scaffold codegen helper files into your project
-  generate    Generate a bounded context skeleton from Zod schemas
+  init          Scaffold codegen helper files into your project
+  generate      Generate a bounded context skeleton from Zod schemas
+  validate      Run pre-flight checks on context or composition configs
+  inspect-spec  Print the normalized spec as JSON
+  plan          Show what artifacts would be generated
+  diff          Compare planned output against existing manifest
 
 Options:
   --target        For init: directory to write helpers into
-                  For generate: override materialization target directory
+                  For generate/plan/diff: override materialization target directory
   --config        Path to context config (.context.ts) or composition config
   --composition   Treat --config as a composition config (multi-context)
   --version-data  Mirror artifacts to Swamp data layer (requires .swamp/ repo)
+  --dry-run       Run full pipeline but skip file writes (generate only)
   --version       Print version
   --help          Print this help
 `);
@@ -252,6 +497,7 @@ function parseArgs(args) {
 		const arg = args[i];
 		if (arg === "--composition") flags.composition = true;
 		else if (arg === "--version-data") flags["version-data"] = true;
+		else if (arg === "--dry-run") flags["dry-run"] = true;
 		else if (arg.startsWith("--") && i + 1 < args.length && !args[i + 1].startsWith("--")) {
 			flags[arg.slice(2)] = args[i + 1];
 			i++;
@@ -292,7 +538,58 @@ async function main() {
 				configPath: config,
 				composition: flags.composition === true,
 				targetOverride: typeof flags.target === "string" ? flags.target : void 0,
-				versionData: flags["version-data"] === true
+				versionData: flags["version-data"] === true,
+				dryRun: flags["dry-run"] === true
+			});
+			break;
+		}
+		case "validate": {
+			const config = flags.config;
+			if (typeof config !== "string") {
+				console.error("Error: --config <path> is required for validate");
+				process.exit(1);
+			}
+			await runValidate({
+				configPath: config,
+				composition: flags.composition === true
+			});
+			break;
+		}
+		case "inspect-spec": {
+			const config = flags.config;
+			if (typeof config !== "string") {
+				console.error("Error: --config <path> is required for inspect-spec");
+				process.exit(1);
+			}
+			await runInspect({
+				configPath: config,
+				composition: flags.composition === true
+			});
+			break;
+		}
+		case "plan": {
+			const config = flags.config;
+			if (typeof config !== "string") {
+				console.error("Error: --config <path> is required for plan");
+				process.exit(1);
+			}
+			await runPlan({
+				configPath: config,
+				composition: flags.composition === true,
+				targetOverride: typeof flags.target === "string" ? flags.target : void 0
+			});
+			break;
+		}
+		case "diff": {
+			const config = flags.config;
+			if (typeof config !== "string") {
+				console.error("Error: --config <path> is required for diff");
+				process.exit(1);
+			}
+			await runDiff({
+				configPath: config,
+				composition: flags.composition === true,
+				targetOverride: typeof flags.target === "string" ? flags.target : void 0
 			});
 			break;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zodmire/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "type": "module",
   "main": "./mod.mjs",
@@ -13,8 +13,8 @@
     }
   },
   "dependencies": {
-    "@zodmire/config": "^0.1.2",
-    "@zodmire/core": "^0.1.2"
+    "@zodmire/config": "^0.1.3",
+    "@zodmire/core": "^0.1.3"
   },
   "bin": {
     "zodmire": "./bin/zodmire.js"