@inlang/sdk 2.5.0 → 2.6.1

package/src/project/path-helpers.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "vitest";
+import { Volume } from "memfs";
+import { absolutePathFromProject, withAbsolutePaths } from "./path-helpers.js";
+
+describe("absolutePathFromProject", () => {
+	test("resolves relative paths against the project root", () => {
+		const result = absolutePathFromProject(
+			"/website/project.inlang",
+			"./local-plugins/mock-plugin.js"
+		);
+
+		expect(result).toBe("/website/local-plugins/mock-plugin.js");
+	});
+
+	test("keeps absolute paths unchanged", () => {
+		const result = absolutePathFromProject(
+			"/website/project.inlang",
+			"/shared/plugins/plugin.js"
+		);
+
+		expect(result).toBe("/shared/plugins/plugin.js");
+	});
+});
+
+describe("withAbsolutePaths", () => {
+	test("maps read/write operations to the project root", async () => {
+		const volume = Volume.fromJSON({
+			"/website/local-plugins/mock-plugin.js": "plugin code",
+		});
+		const mappedFs = withAbsolutePaths(
+			volume.promises as any,
+			"/website/project.inlang"
+		);
+
+		const content = await mappedFs.readFile("./local-plugins/mock-plugin.js");
+		expect(content.toString()).toBe("plugin code");
+
+		await mappedFs.writeFile("./local-plugins/new-plugin.js", "new plugin");
+		const created = await volume.promises.readFile(
+			"/website/local-plugins/new-plugin.js",
+			"utf-8"
+		);
+		expect(created).toBe("new plugin");
+	});
+});

package/src/project/path-helpers.ts

@@ -0,0 +1,71 @@
+import nodePath from "node:path";
+import type { NodeFsPromisesSubsetLegacy } from "../plugin/schema.js";
+
+/**
+ * Functions from a path like `./local-plugins/mock-plugin.js` need to be able
+ * to be called with relative paths, even if their implementation expects absolute ones.
+ *
+ * This mapping is required for backwards compatibility.
+ * Relative paths in the project.inlang/settings.json
+ * file are resolved to absolute paths with `*.inlang`
+ * being pruned.
+ *
+ * @example
+ *   "/website/project.inlang"
+ *   "./local-plugins/mock-plugin.js"
+ *   -> "/website/local-plugins/mock-plugin.js"
+ *
+ */
+export function withAbsolutePaths(
+	fs: NodeFsPromisesSubsetLegacy,
+	projectPath: string
+): NodeFsPromisesSubsetLegacy {
+	return {
+		// @ts-expect-error - node type mismatch
+		readFile: (path, options) => {
+			return fs.readFile(absolutePathFromProject(projectPath, path), options);
+		},
+		writeFile: (path, data) => {
+			return fs.writeFile(absolutePathFromProject(projectPath, path), data);
+		},
+		mkdir: (path) => {
+			return fs.mkdir(absolutePathFromProject(projectPath, path));
+		},
+		readdir: (path) => {
+			return fs.readdir(absolutePathFromProject(projectPath, path));
+		},
+	};
+}
+
+/**
+ * Joins a path from a project path.
+ *
+ * @example
+ *   absolutePathFromProject("/project.inlang", "./local-plugins/mock-plugin.js") -> "/local-plugins/mock-plugin.js"
+ *
+ *   absolutePathFromProject("/website/project.inlang", "./mock-plugin.js") -> "/website/mock-plugin.js"
+ */
+export function absolutePathFromProject(
+	projectPath: string,
+	filePath: string
+): string {
+	// Normalize paths for consistency across platforms
+	const normalizedProjectPath = nodePath
+		.normalize(projectPath)
+		.replace(/\\/g, "/");
+	const normalizedFilePath = nodePath.normalize(filePath).replace(/\\/g, "/");
+
+	// Remove the last part of the project path (file name) to get the project root
+	const projectRoot = nodePath.dirname(normalizedProjectPath);
+
+	// If filePath is already absolute, return it directly
+	if (nodePath.isAbsolute(normalizedFilePath)) {
+		return normalizedFilePath;
+	}
+
+	// Compute absolute resolved path
+	const resolvedPath = nodePath.resolve(projectRoot, normalizedFilePath);
+
+	// Ensure final path always uses forward slashes
+	return resolvedPath.replace(/\\/g, "/");
+}

package/src/project/saveProjectToDirectory.test.ts

@@ -9,6 +9,7 @@ import { loadProjectFromDirectory } from "./loadProjectFromDirectory.js";
 import { selectBundleNested } from "../query-utilities/selectBundleNested.js";
 import type { ProjectSettings } from "../json-schema/settings.js";
 import type { MessageV1 } from "../json-schema/old-v1-message/schemaV1.js";
+import { ENV_VARIABLES } from "../services/env-variables/index.js";
 
 test("it should throw if the path doesn't end with .inlang", async () => {
 	await expect(() =>
@@ -355,9 +356,8 @@ test("adds a gitignore file if it doesn't exist", async () => {
 		"/foo/bar.inlang/.gitignore",
 		"utf-8"
 	);
-	expect(gitignore).toBe(
-		"# this file is auto generated\n# everything is ignored except settings.json\n*\n!settings.json"
-	);
+	expect(gitignore).toContain("*");
+	expect(gitignore).toContain("!settings.json");
 });
 
 test("emits a README.md file for coding agents", async () => {
@@ -377,11 +377,33 @@ test("emits a README.md file for coding agents", async () => {
 		"/foo/bar.inlang/README.md",
 		"utf-8"
 	);
-	expect(readme).toContain("// this readme is auto generated");
 	expect(readme).toContain("## What is this folder?");
 	expect(readme).toContain("@inlang/sdk");
 });
 
+test("emits a .meta.json file with the sdk version", async () => {
+	const fs = Volume.fromJSON({});
+
+	const project = await loadProjectInMemory({
+		blob: await newProject(),
+	});
+
+	await saveProjectToDirectory({
+		fs: fs.promises as any,
+		project,
+		path: "/foo/bar.inlang",
+	});
+
+	const metaRaw = await fs.promises.readFile(
+		"/foo/bar.inlang/.meta.json",
+		"utf-8"
+	);
+	const meta = JSON.parse(
+		typeof metaRaw === "string" ? metaRaw : metaRaw.toString()
+	);
+	expect(meta.highestSdkVersion).toBe(ENV_VARIABLES.SDK_VERSION);
+});
+
 test("updates an existing README.md file", async () => {
 	const fs = Volume.fromJSON({
 		"/foo/bar.inlang/README.md": "custom readme",
@@ -401,10 +423,87 @@ test("updates an existing README.md file", async () => {
 		"/foo/bar.inlang/README.md",
 		"utf-8"
 	);
-	expect(readme).toContain("// this readme is auto generated");
 	expect(readme).not.toContain("custom readme");
 });
 
+test("does not overwrite README.md or .gitignore when meta has a higher sdk version", async () => {
+	const fs = Volume.fromJSON({
+		"/foo/bar.inlang/.meta.json": JSON.stringify({
+			highestSdkVersion: "99.0.0",
+		}),
+		"/foo/bar.inlang/README.md": "custom readme",
+		"/foo/bar.inlang/.gitignore": "custom gitignore",
+	});
+
+	const project = await loadProjectInMemory({
+		blob: await newProject(),
+	});
+
+	await saveProjectToDirectory({
+		fs: fs.promises as any,
+		project,
+		path: "/foo/bar.inlang",
+	});
+
+	const readme = await fs.promises.readFile(
+		"/foo/bar.inlang/README.md",
+		"utf-8"
+	);
+	const gitignore = await fs.promises.readFile(
+		"/foo/bar.inlang/.gitignore",
+		"utf-8"
+	);
+	const metaRaw = await fs.promises.readFile(
+		"/foo/bar.inlang/.meta.json",
+		"utf-8"
+	);
+	const meta = JSON.parse(
+		typeof metaRaw === "string" ? metaRaw : metaRaw.toString()
+	);
+	expect(readme).toBe("custom readme");
+	expect(gitignore).toBe("custom gitignore");
+	expect(meta.highestSdkVersion).toBe("99.0.0");
+});
+
+test("recreates missing README.md and .gitignore when meta has a higher sdk version", async () => {
+	const fs = Volume.fromJSON({
+		"/foo/bar.inlang/.meta.json": JSON.stringify({
+			highestSdkVersion: "99.0.0",
+		}),
+	});
+
+	const project = await loadProjectInMemory({
+		blob: await newProject(),
+	});
+
+	await saveProjectToDirectory({
+		fs: fs.promises as any,
+		project,
+		path: "/foo/bar.inlang",
+	});
+
+	const readme = await fs.promises.readFile(
+		"/foo/bar.inlang/README.md",
+		"utf-8"
+	);
+	const gitignore = await fs.promises.readFile(
+		"/foo/bar.inlang/.gitignore",
+		"utf-8"
+	);
+	const metaRaw = await fs.promises.readFile(
+		"/foo/bar.inlang/.meta.json",
+		"utf-8"
+	);
+	const meta = JSON.parse(
+		typeof metaRaw === "string" ? metaRaw : metaRaw.toString()
+	);
+
+	expect(readme).toContain("## What is this folder?");
+	expect(gitignore).toContain("*");
+	expect(gitignore).toContain("!settings.json");
+	expect(meta.highestSdkVersion).toBe("99.0.0");
+});
+
 test("README.md is gitignored", async () => {
 	const fs = Volume.fromJSON({});
 
@@ -422,7 +521,6 @@ test("README.md is gitignored", async () => {
 		"/foo/bar.inlang/.gitignore",
 		"utf-8"
 	);
-	expect(gitignore).toContain("# this file is auto generated");
 	expect(gitignore).toContain("# everything is ignored except settings.json");
 	expect(gitignore).toContain("*");
 	expect(gitignore).toContain("!settings.json");
@@ -448,9 +546,8 @@ test("overwrites existing .gitignore with generated entries", async () => {
 		"/foo/bar.inlang/.gitignore",
 		"utf-8"
 	);
-	expect(gitignore).toBe(
-		"# this file is auto generated\n# everything is ignored except settings.json\n*\n!settings.json"
-	);
+	expect(gitignore).toContain("*");
+	expect(gitignore).toContain("!settings.json");
 });
 
 test("uses exportFiles when both exportFiles and saveMessages are defined", async () => {
@@ -475,6 +572,29 @@ test("uses exportFiles when both exportFiles and saveMessages are defined", asyn
 	expect(saveMessagesSpy).not.toHaveBeenCalled();
 });
 
+test("skipExporting prevents exporters from running", async () => {
+	const exportFilesSpy = vi.fn().mockResolvedValue([]);
+	const saveMessagesSpy = vi.fn();
+	const mockPlugin: InlangPlugin = {
+		key: "mock",
+		exportFiles: exportFilesSpy,
+		saveMessages: saveMessagesSpy,
+	};
+	const volume = Volume.fromJSON({});
+	const project = await loadProjectInMemory({
+		blob: await newProject(),
+		providePlugins: [mockPlugin],
+	});
+	await saveProjectToDirectory({
+		path: "/foo/project.inlang",
+		fs: volume.promises as any,
+		project,
+		skipExporting: true,
+	});
+	expect(exportFilesSpy).not.toHaveBeenCalled();
+	expect(saveMessagesSpy).not.toHaveBeenCalled();
+});
+
 test("uses saveMessages when exportFiles is not defined", async () => {
 	const saveMessagesSpy = vi.fn().mockResolvedValue([]);
 	const mockPlugin: InlangPlugin = {

package/src/project/saveProjectToDirectory.ts

@@ -2,18 +2,55 @@ import type fs from "node:fs/promises";
 import type { InlangProject } from "./api.js";
 import path from "node:path";
 import { toMessageV1 } from "../json-schema/old-v1-message/toMessageV1.js";
-import {
-	absolutePathFromProject,
-	withAbsolutePaths,
-} from "./loadProjectFromDirectory.js";
+import { absolutePathFromProject, withAbsolutePaths } from "./path-helpers.js";
 import { detectJsonFormatting } from "../utilities/detectJsonFormatting.js";
 import { selectBundleNested } from "../query-utilities/selectBundleNested.js";
 import { README_CONTENT } from "./README_CONTENT.js";
+import { ENV_VARIABLES } from "../services/env-variables/index.js";
+import { compareSemver, pickHighestVersion, readProjectMeta } from "./meta.js";
 
+async function fileExists(fsModule: typeof fs, filePath: string) {
+	try {
+		await fsModule.stat(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Saves a project to a directory.
+ *
+ * Writes all project files to disk and runs exporters to generate
+ * resource files (e.g., JSON translation files).
+ *
+ * @example
+ *   await saveProjectToDirectory({
+ *     fs: await import("node:fs/promises"),
+ *     project,
+ *     path: "./project.inlang",
+ *   });
+ */
 export async function saveProjectToDirectory(args: {
+	/**
+	 * The file system module to use for writing files.
+	 */
 	fs: typeof fs;
+	/**
+	 * The inlang project to save.
+	 */
 	project: InlangProject;
+	/**
+	 * The path to the inlang project directory. Must end with `.inlang`.
+	 */
 	path: string;
+	/**
+	 * If `true`, skips running exporters and only writes internal project files.
+	 *
+	 * Useful when you only want to update project metadata without
+	 * regenerating resource files.
+	 */
+	skipExporting?: boolean;
 }): Promise<void> {
 	if (args.path.endsWith(".inlang") === false) {
 		throw new Error("The path must end with .inlang");
@@ -24,9 +61,32 @@ export async function saveProjectToDirectory(args: {
 		.execute();
 
 	const gitignoreContent = new TextEncoder().encode(
-		"# this file is auto generated\n# everything is ignored except settings.json\n*\n!settings.json"
+		"# IF GIT SHOWED THAT THIS FILE CHANGED\n#\n# 1. RUN THE FOLLOWING COMMAND\n#\n# ---\n# git rm --cached '**/*.inlang/.gitignore'\n# ---\n#\n# 2. COMMIT THE CHANGE\n#\n# ---\n# git commit -m \"fix: remove tracked .gitignore from inlang project\"\n# ---\n#\n# Inlang handles the gitignore itself starting with version ^2.5.\n#\n# everything is ignored except settings.json\n*\n!settings.json"
 	);
 
+	const existingMeta = await readProjectMeta({
+		fs: args.fs,
+		projectPath: args.path,
+	});
+	const highestSdkVersion =
+		pickHighestVersion([
+			existingMeta?.highestSdkVersion,
+			ENV_VARIABLES.SDK_VERSION,
+		]) ?? ENV_VARIABLES.SDK_VERSION;
+	const shouldWriteMetadata = (() => {
+		const comparison = compareSemver(
+			highestSdkVersion,
+			ENV_VARIABLES.SDK_VERSION
+		);
+		return comparison === null || comparison <= 0;
+	})();
+	const readmePath = path.join(args.path, "README.md");
+	const gitignorePath = path.join(args.path, ".gitignore");
+	const shouldWriteReadme =
+		shouldWriteMetadata || !(await fileExists(args.fs, readmePath));
+	const shouldWriteGitignore =
+		shouldWriteMetadata || !(await fileExists(args.fs, gitignorePath));
+
 	// write all files to the directory
 	for (const file of files) {
 		if (file.path.endsWith("db.sqlite") || file.path === "/project_id") {
@@ -37,13 +97,29 @@ export async function saveProjectToDirectory(args: {
 		await args.fs.writeFile(p, new Uint8Array(file.data));
 	}
 
-	await args.fs.writeFile(path.join(args.path, ".gitignore"), gitignoreContent);
+	if (shouldWriteGitignore) {
+		await args.fs.writeFile(gitignorePath, gitignoreContent);
+	}
 
-	// Write README.md for coding agents
-	await args.fs.writeFile(
-		path.join(args.path, "README.md"),
-		new TextEncoder().encode(README_CONTENT)
-	);
+	if (shouldWriteReadme) {
+		// Write README.md for coding agents
+		await args.fs.writeFile(
+			readmePath,
+			new TextEncoder().encode(README_CONTENT)
+		);
+	}
+
+	if (shouldWriteMetadata) {
+		const metaContent = JSON.stringify({ highestSdkVersion }, null, 2);
+		await args.fs.writeFile(
+			path.join(args.path, ".meta.json"),
+			new TextEncoder().encode(metaContent)
+		);
+	}
+
+	if (args.skipExporting) {
+		return;
+	}
 
 	// run exporters
 	const plugins = await args.project.plugins.get();