simplify contract

Author: Mathiyarasy

src/spec-configuration/configuration.ts

@@ -38,17 +38,10 @@ export interface DevContainerFeature {
 	options: boolean | string | Record<string, boolean | string | undefined>;
 }
 
-// Dockerfile preprocessing always produces a CLI-owned final Dockerfile path.
-// Users provide the preprocessor tool and optional arguments.
-// For direct file transforms, users can select whether the tool behaves like a
-// single-file transform or expects a build-tree style workspace argument.
-// For workspace-style generators, users can instead set generatedDockerfile to
-// tell the CLI which file to promote to the final Dockerfile after the tool runs.
 export interface DockerfilePreprocessor {
 	tool?: string;
 	args?: string[];
-	outputMode?: 'single-file' | 'build-tree';
-	generatedDockerfile?: string;
+	generatedDockerfilePath?: string;
 }
 
 export interface DevContainerFromImageConfig {

src/spec-node/dockerfilePreprocessor.ts

@@ -11,86 +11,55 @@ import { runCommandNoPty } from '../spec-common/commonUtils';
 import { Log, LogLevel, makeLog } from '../spec-utils/log';
 
 function dockerfilePreprocessorToolDocs(): string {
-	return "Set 'dockerfilePreprocessor.tool' and optional 'dockerfilePreprocessor.args' in devcontainer.json. 'outputMode' controls CLI invocation shape: 'single-file' passes input/output and 'build-tree' passes input/output/workdir. When using 'build-tree', set 'generatedDockerfile' to the tool's produced Dockerfile path so the CLI can verify and synchronize outputs.";
-}
-
-export function getDockerfilePreprocessedPath(dockerfilePath: string): string | undefined {
-	if (!dockerfilePath.toLowerCase().endsWith('.in')) {
-		return undefined;
-	}
-	return path.join(path.dirname(dockerfilePath), '.devcontainer-preprocessed', 'Dockerfile');
+	return "Set 'dockerfilePreprocessor.tool', optional 'dockerfilePreprocessor.args', and 'dockerfilePreprocessor.generatedDockerfilePath' in devcontainer.json. The CLI invokes the tool with configured args and validates that the generated Dockerfile exists at the configured path.";
 }
 
 export async function preprocessDockerExtensionFile(
 	params: { cliHost: CLIHost; output: Log },
 	config: Pick<DevContainerFromDockerfileConfig | DevContainerFromDockerComposeConfig, 'dockerfilePreprocessor'>,
 	dockerfilePath: string
 ): Promise<string> {
-	const cliOutputPath = getDockerfilePreprocessedPath(dockerfilePath);
-	if (!cliOutputPath) {
-		return dockerfilePath;
-	}
 
 	const tool = config.dockerfilePreprocessor?.tool?.trim();
 	const args = (config.dockerfilePreprocessor?.args || []).map(arg => arg.trim()).filter(arg => arg.length > 0);
-	const outputMode = config.dockerfilePreprocessor?.outputMode || 'build-tree';
-	const generatedDockerfile = config.dockerfilePreprocessor?.generatedDockerfile?.trim();
+	const generatedDockerfilePath = config.dockerfilePreprocessor?.generatedDockerfilePath?.trim();
 	if (!tool) {
 		throw new ContainerError({
 			description: `A Dockerfile preprocessor tool is required to build from '${dockerfilePath}'. ${dockerfilePreprocessorToolDocs()}`,
 			data: { fileWithError: dockerfilePath },
 		});
 	}
-	if (outputMode === 'single-file' && generatedDockerfile) {
-		throw new ContainerError({
-			description: `dockerfilePreprocessor.outputMode 'single-file' cannot be used with 'dockerfilePreprocessor.generatedDockerfile'. Omit generatedDockerfile in single-file mode. ${dockerfilePreprocessorToolDocs()}`,
-			data: { fileWithError: dockerfilePath },
-		});
-	}
-	if (outputMode === 'build-tree' && !generatedDockerfile) {
+	if (!generatedDockerfilePath) {
 		throw new ContainerError({
-			description: `dockerfilePreprocessor.outputMode 'build-tree' requires 'dockerfilePreprocessor.generatedDockerfile' to be set. ${dockerfilePreprocessorToolDocs()}`,
+			description: `dockerfilePreprocessor.generatedDockerfilePath is required. ${dockerfilePreprocessorToolDocs()}`,
 			data: { fileWithError: dockerfilePath },
 		});
 	}
 
 	const { cliHost, output } = params;
 	const infoOutput = makeLog(output, LogLevel.Info);
-	const cliOutputDir = path.dirname(cliOutputPath);
-	await cliHost.mkdirp(cliOutputDir);
 	const workdirPath = path.dirname(dockerfilePath);
-	const inputPath = dockerfilePath;
-	const outputPath = cliOutputPath;
-	const generatedOutputPath = generatedDockerfile ? path.resolve(workdirPath, generatedDockerfile) : outputPath;
-	const staleOutputPaths = generatedOutputPath === outputPath ? [outputPath] : [outputPath, generatedOutputPath];
+	const generatedOutputPath = path.resolve(workdirPath, generatedDockerfilePath);
+	const generatedOutputDir = path.dirname(generatedOutputPath);
+	await cliHost.mkdirp(generatedOutputDir);
+	const staleOutputPaths = [generatedOutputPath];
 	for (const stalePath of staleOutputPaths) {
 		if (!await cliHost.isFile(stalePath)) {
 			continue;
 		}
 		await cliHost.remove(stalePath);
 	}
 
-	// Strict contract: the CLI owns the final output path. Direct-transform
-	// tools can write to the CLI-provided output argument; workspace generators
-	// can instead declare a generated Dockerfile path for the CLI to promote.
+	// Minimal contract: tool args are user-controlled and run in the Dockerfile
+	// directory. The CLI only provides the resolved generated Dockerfile path.
 	const env = {
 		...cliHost.env,
-		DEVCONTAINER_DOCKERFILE_PREPROCESSOR_INPUT: inputPath,
-		DEVCONTAINER_DOCKERFILE_PREPROCESSOR_OUTPUT: outputPath,
-		DEVCONTAINER_DOCKERFILE_PREPROCESSOR_WORKDIR: workdirPath,
 		DEVCONTAINER_DOCKERFILE_PREPROCESSOR_GENERATED_DOCKERFILE: generatedOutputPath,
-		input_file: inputPath,
-		output_file: outputPath,
-		generated_dockerfile: generatedOutputPath,
-		workdir: workdirPath,
 	};
-	const directOutputArgs = outputMode === 'single-file'
-		? [inputPath, outputPath]
-		: [inputPath, outputPath, workdirPath];
-	const invocationArgs = [...args, ...directOutputArgs];
+	const invocationArgs = [...args];
 
 	try {
-		infoOutput.write(`Preprocessing '${dockerfilePath}' -> '${cliOutputPath}'`);
+		infoOutput.write(`Preprocessing '${dockerfilePath}' -> '${generatedOutputPath}'`);
 		await runCommandNoPty({
 			exec: cliHost.exec,
 			cmd: tool,
@@ -121,25 +90,15 @@ export async function preprocessDockerExtensionFile(
 		});
 	}
 
-	if (generatedDockerfile && generatedOutputPath !== outputPath && !await cliHost.isFile(generatedOutputPath) && await cliHost.isFile(outputPath)) {
-		infoOutput.write(`No generated Dockerfile found at '${generatedOutputPath}', copying from CLI output '${outputPath}' to keep generated output consistent.`);
-		await cliHost.copyFile(outputPath, generatedOutputPath);
-	}
-
-	if (!await cliHost.isFile(generatedOutputPath)) {
+	const generatedExists = await cliHost.isFile(generatedOutputPath);
+	if (!generatedExists) {
 		throw new ContainerError({
-			description: generatedDockerfile
-				? `Dockerfile preprocessing did not produce '${generatedOutputPath}'. Ensure the configured tool writes the final Dockerfile to the configured generatedDockerfile path. ${dockerfilePreprocessorToolDocs()}`
-				: `Dockerfile preprocessing did not produce '${outputPath}'. Ensure the configured tool writes the final Dockerfile to the CLI-provided output argument. ${dockerfilePreprocessorToolDocs()}`,
+			description: `Dockerfile preprocessing did not produce '${generatedOutputPath}'. Ensure the configured tool writes the final Dockerfile to the configured generatedDockerfile path. ${dockerfilePreprocessorToolDocs()}`,
 			data: { fileWithError: dockerfilePath },
 		});
 	}
 
-	if (generatedOutputPath !== outputPath) {
-		await cliHost.copyFile(generatedOutputPath, outputPath);
-	}
-
-	infoOutput.write(`Preprocessed Dockerfile written to '${cliOutputPath}'`);
+	infoOutput.write(`Preprocessed Dockerfile written to '${generatedOutputPath}'`);
 
-	return cliOutputPath;
+	return generatedOutputPath;
 }

src/test/configs/dockercomposefile-cpp-preprocessor/.devcontainer/Dockerfile.in

@@ -0,0 +1,16 @@
+#define BASE_IMAGE ubuntu:20.04
+#define INSTALL_NODE
+#define INSTALL_PYTHON
+
+FROM BASE_IMAGE
+
+#ifdef INSTALL_NODE
+RUN apt-get update && apt-get install -y nodejs
+#endif
+
+#ifdef INSTALL_PYTHON
+RUN apt-get update && apt-get install -y python3
+#endif
+
+#include "common.Dockerfile"
+#include "tools.Dockerfile"

src/test/configs/dockercomposefile-cpp-preprocessor/.devcontainer/devcontainer.json

@@ -5,14 +5,14 @@
 	"workspaceFolder": "/workspace",
 	"dockerfilePreprocessor": {
 		"tool": "cpp",
-		"outputMode": "single-file",
+		"generatedDockerfilePath": "Dockerfile",
 		"args": [
-			"-P"
+			"-P",
+			"Dockerfile.in",
+			"Dockerfile"
 		]
 	},
 	"features": {
-		"ghcr.io/devcontainers/features/github-cli:1": {
-			"version": "latest"
-		}
+		"ghcr.io/devcontainers/features/git": "latest"
 	}
 }

src/test/configs/dockerfile-autoconf-preprocessor/.devcontainer.json

@@ -8,7 +8,7 @@
 			"-c",
 			"autoconf && ./configure"
 		],
-		"generatedDockerfile": "Dockerfile"
+		"generatedDockerfilePath": "Dockerfile"
 	},
 	"features": {
 		"ghcr.io/devcontainers/features/github-cli:1": {

src/test/configs/dockerfile-cmake-preprocessor/.devcontainer.json

@@ -10,7 +10,7 @@
 			"-B",
 			"build"
 		],
-		"generatedDockerfile": "build/Dockerfile"
+		"generatedDockerfilePath": "build/Dockerfile"
 	},
 	"features": {
 		"ghcr.io/devcontainers/features/github-cli:1": {

src/test/configs/dockerfile-cmake2-preprocessor/.devcontainer.json

@@ -10,7 +10,7 @@
 			"-B",
 			"build"
 		],
-		"generatedDockerfile": "Dockerfile"
+		"generatedDockerfilePath": "Dockerfile"
 	},
 	"features": {
 		"ghcr.io/devcontainers/features/github-cli:1": {

src/test/configs/dockerfile-cpp-preprocessor/.devcontainer.json

@@ -4,10 +4,12 @@
 	},
 	"dockerfilePreprocessor": {
 		"tool": "cpp",
-		"outputMode": "single-file",
 		"args": [
-			"-P"
-		]
+			"-P",
+			"./Dockerfile.in",
+			"Dockerfile"
+		],
+		"generatedDockerfilePath": "Dockerfile"
 	},
 	"features": {
 		"ghcr.io/devcontainers/features/github-cli:1": {

src/test/configs/dockerfile-meson-preprocessor/.devcontainer.json

@@ -8,7 +8,7 @@
 			"setup",
 			"build"
 		],
-		"generatedDockerfile": "build/Dockerfile"
+		"generatedDockerfilePath": "build/Dockerfile"
 	},
 	"features": {
 		"ghcr.io/devcontainers/features/github-cli:1": {