@intlayer/engine 9.0.0-canary.13 → 9.0.0-canary.14

package/dist/esm/writeFileIfChanged.mjs

@@ -1,7 +1,7 @@
-import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { createHash, randomBytes } from "node:crypto";
-import { createReadStream, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { rmSync } from "node:fs";
 
 //#region src/writeFileIfChanged.ts
 const activeTempFiles = /* @__PURE__ */ new Set();
@@ -10,28 +10,52 @@ process.on("exit", () => {
 		rmSync(file, { force: true });
 	} catch {}
 });
-const getFileHash = (path) => {
-	return new Promise((resolve) => {
-		const hash = createHash("sha256");
-		const stream = createReadStream(path);
-		stream.on("data", (chunk) => hash.update(chunk));
-		stream.on("end", () => resolve(hash.digest("hex")));
-		stream.on("error", () => resolve(null));
-	});
-};
-const writeFileIfChanged = async (path, data, { encoding = "utf8", tempDir } = {}) => {
-	if (createHash("sha256").update(data, encoding).digest("hex") === await getFileHash(path)) return false;
+/**
+* Permission bits a freshly created file receives on this system. Detected once
+* from the first temp file we actually write (`process.umask()` with no
+* argument is deprecated and thread-unsafe) and cached, so the atomic path can
+* skip restoring the mode whenever the source file already uses the default
+* mode — which is the case for essentially every generated file.
+*/
+let defaultFileMode;
+/**
+* Write `data` to `path` only when it differs from the file already on disk,
+* preserving the existing file's permission mode.
+*
+* The whole file is read back and byte-compared because the files written here
+* (dictionaries, entry points, types) are small, so reading beats streaming a
+* hash. When the content is unchanged the write is skipped entirely, which both
+* avoids inode churn and prevents downstream watchers from rebuilding.
+*
+* @returns `true` when the file was written, `false` when it was already up to date.
+*/
+const writeFileIfChanged = async (path, data, { encoding = "utf8", tempDir, atomic = true } = {}) => {
+	const newData = Buffer.from(data, encoding);
+	let existingData = null;
+	try {
+		existingData = await readFile(path);
+	} catch {}
+	if (existingData?.equals(newData)) return false;
+	if (!atomic) {
+		await writeFile(path, newData);
+		return true;
+	}
+	let modeToRestore;
+	if (existingData !== null) try {
+		modeToRestore = (await stat(path)).mode & 511;
+	} catch {}
 	if (tempDir) await mkdir(tempDir, { recursive: true });
 	const tempFileName = `${basename(path)}.${Date.now()}-${randomBytes(4).toString("hex")}.tmp`;
 	const tempPath = tempDir ? join(tempDir, tempFileName) : `${path}.${tempFileName}`;
 	activeTempFiles.add(tempPath);
 	try {
-		let mode;
-		try {
-			mode = (await stat(path)).mode;
-		} catch {}
-		await writeFile(tempPath, data, { encoding });
-		if (mode !== void 0) await chmod(tempPath, mode);
+		await writeFile(tempPath, newData);
+		if (modeToRestore !== void 0) {
+			if (defaultFileMode === void 0) try {
+				defaultFileMode = (await stat(tempPath)).mode & 511;
+			} catch {}
+			if (modeToRestore !== defaultFileMode) await chmod(tempPath, modeToRestore);
+		}
 		await rename(tempPath, path);
 	} catch (error) {
 		try {

package/dist/esm/writeFileIfChanged.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"writeFileIfChanged.mjs","names":[],"sources":["../../src/writeFileIfChanged.ts"],"sourcesContent":["import { createHash, randomBytes } from 'node:crypto';\nimport { createReadStream, rmSync } from 'node:fs';\nimport { chmod, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';\nimport { basename, join } from 'node:path';\n\nconst activeTempFiles = new Set<string>();\n\n// Synchronous cleanup on process exit\nprocess.on('exit', () => {\n  for (const file of activeTempFiles) {\n    try {\n      rmSync(file, { force: true });\n    } catch {}\n  }\n});\n\n// Helper to hash existing file via stream\nconst getFileHash = (path: string): Promise<string | null> => {\n  return new Promise((resolve) => {\n    const hash = createHash('sha256');\n    const stream = createReadStream(path);\n    stream.on('data', (chunk) => hash.update(chunk));\n    stream.on('end', () => resolve(hash.digest('hex')));\n    stream.on('error', () => resolve(null));\n  });\n};\n\nexport const writeFileIfChanged = async (\n  path: string,\n  data: string,\n  {\n    encoding = 'utf8',\n    tempDir,\n  }: { encoding?: BufferEncoding; tempDir?: string } = {}\n): Promise<boolean> => {\n  const newDataHash = createHash('sha256').update(data, encoding).digest('hex');\n  const existingHash = await getFileHash(path);\n\n  if (newDataHash === existingHash) {\n    return false;\n  }\n\n  if (tempDir) {\n    await mkdir(tempDir, { recursive: true });\n  }\n\n  const tempFileName = `${basename(path)}.${Date.now()}-${randomBytes(4).toString('hex')}.tmp`;\n  const tempPath = tempDir\n    ? join(tempDir, tempFileName)\n    : `${path}.${tempFileName}`;\n  activeTempFiles.add(tempPath);\n\n  try {\n    let mode: number | undefined;\n    try {\n      mode = (await stat(path)).mode;\n    } catch {}\n\n    await writeFile(tempPath, data, { encoding });\n\n    if (mode !== undefined) {\n      await chmod(tempPath, mode);\n    }\n\n    await rename(tempPath, path);\n  } catch (error) {\n    try {\n      await rm(tempPath, { force: true });\n    } catch {}\n    throw error;\n  } finally {\n    activeTempFiles.delete(tempPath);\n  }\n\n  return true;\n};\n"],"mappings":";;;;;;AAKA,MAAM,kCAAkB,IAAI,KAAa;AAGzC,QAAQ,GAAG,cAAc;AACvB,MAAK,MAAM,QAAQ,gBACjB,KAAI;AACF,SAAO,MAAM,EAAE,OAAO,MAAM,CAAC;SACvB;EAEV;AAGF,MAAM,eAAe,SAAyC;AAC5D,QAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,OAAO,WAAW,SAAS;EACjC,MAAM,SAAS,iBAAiB,KAAK;AACrC,SAAO,GAAG,SAAS,UAAU,KAAK,OAAO,MAAM,CAAC;AAChD,SAAO,GAAG,aAAa,QAAQ,KAAK,OAAO,MAAM,CAAC,CAAC;AACnD,SAAO,GAAG,eAAe,QAAQ,KAAK,CAAC;GACvC;;AAGJ,MAAa,qBAAqB,OAChC,MACA,MACA,EACE,WAAW,QACX,YACmD,EAAE,KAClC;AAIrB,KAHoB,WAAW,SAAS,CAAC,OAAO,MAAM,SAAS,CAAC,OAAO,MAGxD,KAAK,MAFO,YAAY,KAAK,CAG1C,QAAO;AAGT,KAAI,QACF,OAAM,MAAM,SAAS,EAAE,WAAW,MAAM,CAAC;CAG3C,MAAM,eAAe,GAAG,SAAS,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC;CACvF,MAAM,WAAW,UACb,KAAK,SAAS,aAAa,GAC3B,GAAG,KAAK,GAAG;AACf,iBAAgB,IAAI,SAAS;AAE7B,KAAI;EACF,IAAI;AACJ,MAAI;AACF,WAAQ,MAAM,KAAK,KAAK,EAAE;UACpB;AAER,QAAM,UAAU,UAAU,MAAM,EAAE,UAAU,CAAC;AAE7C,MAAI,SAAS,OACX,OAAM,MAAM,UAAU,KAAK;AAG7B,QAAM,OAAO,UAAU,KAAK;UACrB,OAAO;AACd,MAAI;AACF,SAAM,GAAG,UAAU,EAAE,OAAO,MAAM,CAAC;UAC7B;AACR,QAAM;WACE;AACR,kBAAgB,OAAO,SAAS;;AAGlC,QAAO"}
+{"version":3,"file":"writeFileIfChanged.mjs","names":[],"sources":["../../src/writeFileIfChanged.ts"],"sourcesContent":["import { randomBytes } from 'node:crypto';\nimport { rmSync } from 'node:fs';\nimport {\n  chmod,\n  mkdir,\n  readFile,\n  rename,\n  rm,\n  stat,\n  writeFile,\n} from 'node:fs/promises';\nimport { basename, join } from 'node:path';\n\nconst activeTempFiles = new Set<string>();\n\n// Synchronous cleanup on process exit\nprocess.on('exit', () => {\n  for (const file of activeTempFiles) {\n    try {\n      rmSync(file, { force: true });\n    } catch {}\n  }\n});\n\n/**\n * Permission bits a freshly created file receives on this system. Detected once\n * from the first temp file we actually write (`process.umask()` with no\n * argument is deprecated and thread-unsafe) and cached, so the atomic path can\n * skip restoring the mode whenever the source file already uses the default\n * mode — which is the case for essentially every generated file.\n */\nlet defaultFileMode: number | undefined;\n\n/**\n * Options for {@link writeFileIfChanged}.\n */\nexport type WriteFileIfChangedOptions = {\n  /** Encoding used to turn `data` into bytes. Defaults to `'utf8'`. */\n  encoding?: BufferEncoding;\n  /** Directory to hold the temporary file used for the atomic swap. */\n  tempDir?: string;\n  /**\n   * Write atomically via a temp file + `rename` so readers never observe a\n   * half-written file. This creates a fresh inode on every write, which roughly\n   * doubles the cost of a changed write compared to overwriting in place. Set to\n   * `false` for callers whose consumers tolerate torn reads to write directly.\n   * Defaults to `true`.\n   */\n  atomic?: boolean;\n};\n\n/**\n * Write `data` to `path` only when it differs from the file already on disk,\n * preserving the existing file's permission mode.\n *\n * The whole file is read back and byte-compared because the files written here\n * (dictionaries, entry points, types) are small, so reading beats streaming a\n * hash. When the content is unchanged the write is skipped entirely, which both\n * avoids inode churn and prevents downstream watchers from rebuilding.\n *\n * @returns `true` when the file was written, `false` when it was already up to date.\n */\nexport const writeFileIfChanged = async (\n  path: string,\n  data: string,\n  { encoding = 'utf8', tempDir, atomic = true }: WriteFileIfChangedOptions = {}\n): Promise<boolean> => {\n  const newData = Buffer.from(data, encoding);\n\n  // Read the current content first: the common case is an unchanged file, and\n  // this single read is the whole fast path (no stat/chmod needed to bail out).\n  let existingData: Buffer | null = null;\n  try {\n    existingData = await readFile(path);\n  } catch {}\n\n  if (existingData?.equals(newData)) {\n    return false;\n  }\n\n  // Fast path: overwrite in place. Truncating an existing file keeps its inode,\n  // so its permission mode is preserved automatically (no chmod needed). This\n  // skips the temp-file inode churn at the cost of exposing readers to a\n  // partially written file.\n  if (!atomic) {\n    await writeFile(path, newData);\n    return true;\n  }\n\n  // The atomic swap replaces the inode, so the existing mode is not preserved\n  // and must be reapplied. Only a file that already exists has a mode to keep.\n  let modeToRestore: number | undefined;\n  if (existingData !== null) {\n    try {\n      modeToRestore = (await stat(path)).mode & 0o777;\n    } catch {}\n  }\n\n  if (tempDir) {\n    await mkdir(tempDir, { recursive: true });\n  }\n\n  const tempFileName = `${basename(path)}.${Date.now()}-${randomBytes(4).toString('hex')}.tmp`;\n  const tempPath = tempDir\n    ? join(tempDir, tempFileName)\n    : `${path}.${tempFileName}`;\n  activeTempFiles.add(tempPath);\n\n  try {\n    await writeFile(tempPath, newData);\n\n    if (modeToRestore !== undefined) {\n      // Learn the ambient default mode once from a real temp file, then only\n      // chmod when the source file used a non-default mode.\n      if (defaultFileMode === undefined) {\n        try {\n          defaultFileMode = (await stat(tempPath)).mode & 0o777;\n        } catch {}\n      }\n      if (modeToRestore !== defaultFileMode) {\n        await chmod(tempPath, modeToRestore);\n      }\n    }\n\n    await rename(tempPath, path);\n  } catch (error) {\n    try {\n      await rm(tempPath, { force: true });\n    } catch {}\n    throw error;\n  } finally {\n    activeTempFiles.delete(tempPath);\n  }\n\n  return true;\n};\n"],"mappings":";;;;;;AAaA,MAAM,kCAAkB,IAAI,KAAa;AAGzC,QAAQ,GAAG,cAAc;AACvB,MAAK,MAAM,QAAQ,gBACjB,KAAI;AACF,SAAO,MAAM,EAAE,OAAO,MAAM,CAAC;SACvB;EAEV;;;;;;;;AASF,IAAI;;;;;;;;;;;;AA+BJ,MAAa,qBAAqB,OAChC,MACA,MACA,EAAE,WAAW,QAAQ,SAAS,SAAS,SAAoC,EAAE,KACxD;CACrB,MAAM,UAAU,OAAO,KAAK,MAAM,SAAS;CAI3C,IAAI,eAA8B;AAClC,KAAI;AACF,iBAAe,MAAM,SAAS,KAAK;SAC7B;AAER,KAAI,cAAc,OAAO,QAAQ,CAC/B,QAAO;AAOT,KAAI,CAAC,QAAQ;AACX,QAAM,UAAU,MAAM,QAAQ;AAC9B,SAAO;;CAKT,IAAI;AACJ,KAAI,iBAAiB,KACnB,KAAI;AACF,mBAAiB,MAAM,KAAK,KAAK,EAAE,OAAO;SACpC;AAGV,KAAI,QACF,OAAM,MAAM,SAAS,EAAE,WAAW,MAAM,CAAC;CAG3C,MAAM,eAAe,GAAG,SAAS,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,YAAY,EAAE,CAAC,SAAS,MAAM,CAAC;CACvF,MAAM,WAAW,UACb,KAAK,SAAS,aAAa,GAC3B,GAAG,KAAK,GAAG;AACf,iBAAgB,IAAI,SAAS;AAE7B,KAAI;AACF,QAAM,UAAU,UAAU,QAAQ;AAElC,MAAI,kBAAkB,QAAW;AAG/B,OAAI,oBAAoB,OACtB,KAAI;AACF,uBAAmB,MAAM,KAAK,SAAS,EAAE,OAAO;WAC1C;AAEV,OAAI,kBAAkB,gBACpB,OAAM,MAAM,UAAU,cAAc;;AAIxC,QAAM,OAAO,UAAU,KAAK;UACrB,OAAO;AACd,MAAI;AACF,SAAM,GAAG,UAAU,EAAE,OAAO,MAAM,CAAC;UAC7B;AACR,QAAM;WACE;AACR,kBAAgB,OAAO,SAAS;;AAGlC,QAAO"}

package/dist/types/createType/createType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createType.d.ts","names":[],"sources":["../../../src/createType/createType.ts"],"mappings":";;;;cASa,sBAAA,GACX,UAAA,EAAY,UAAA,GAAa,wBAAA;;AAD3B;;cAUa,WAAA,GACX,YAAA,GAAe,UAAA,GAAa,wBAAA,KAC5B,aAAA,EAAe,cAAA,KACd,OAAA"}
+{"version":3,"file":"createType.d.ts","names":[],"sources":["../../../src/createType/createType.ts"],"mappings":";;;;cAUa,sBAAA,GACX,UAAA,EAAY,UAAA,GAAa,wBAAA;;AAD3B;;cAUa,WAAA,GACX,YAAA,GAAe,UAAA,GAAa,wBAAA,KAC5B,aAAA,EAAe,cAAA,KACd,OAAA"}

package/dist/types/syncPluginKit/createFileAdapter.d.ts

@@ -0,0 +1,51 @@
+import { ContentAdapter, FormatCodec, SyncContent, SyncPluginContext } from "./types.js";
+import { FilePathPattern } from "@intlayer/types/filePathPattern";
+
+//#region src/syncPluginKit/createFileAdapter.d.ts
+/**
+ * Discovery strategy of the file adapter:
+ * - `strict`: keep only files whose path rebuilds identically from the source
+ *   pattern, and fabricate entries for missing locales/keys so every declared
+ *   locale has a write-back target (sync plugins).
+ * - `inclusive`: keep every glob match without fabricating missing entries
+ *   (read-only load plugins, whose patterns may contain free `**` globs).
+ */
+type FileAdapterDiscovery = 'strict' | 'inclusive';
+type CreateFileAdapterOptions = {
+  /**
+   * Location of the files, as a static string, a templated string
+   * (e.g. `./messages/{{locale}}/{{key}}.json`) or a function building the
+   * path from the key and locale.
+   */
+  source: FilePathPattern;
+  /**
+   * Format of the files: string payload ↔ structured content.
+   */
+  codec: FormatCodec;
+  /**
+   * Optional override of how one file is read and parsed. Defaults to a plain
+   * utf-8 read followed by `codec.parse`, returning `undefined` for missing or
+   * unreadable files. Adapters needing richer loading (e.g. JSON5 or
+   * transpiled TS sources) provide their own implementation here.
+   */
+  readEntry?: (absoluteFilePath: string, context: SyncPluginContext) => Promise<SyncContent | undefined>;
+  /**
+   * Discovery strategy. Defaults to `'strict'`.
+   */
+  discovery?: FileAdapterDiscovery;
+};
+/**
+ * Create a filesystem {@link ContentAdapter} for `createSyncPlugin`.
+ *
+ * Handles glob discovery of the source pattern, key/locale extraction from
+ * paths, base-directory resolution, and change-detected atomic writes.
+ */
+declare const createFileAdapter: (options: CreateFileAdapterOptions) => ContentAdapter;
+/**
+ * Default `readEntry` implementation: plain utf-8 read followed by the given
+ * parser. Returns `undefined` for missing or unreadable files.
+ */
+declare const createFileReader: (parse: (raw: string) => SyncContent) => (absoluteFilePath: string) => Promise<SyncContent | undefined>;
+//#endregion
+export { CreateFileAdapterOptions, FileAdapterDiscovery, createFileAdapter, createFileReader };
+//# sourceMappingURL=createFileAdapter.d.ts.map

package/dist/types/syncPluginKit/createFileAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFileAdapter.d.ts","names":[],"sources":["../../../src/syncPluginKit/createFileAdapter.ts"],"mappings":";;;;;;AAyBA;;;;;AAEA;KAFY,oBAAA;AAAA,KAEA,wBAAA;EAMF;;;;;EAAR,MAAA,EAAQ,eAAA;EAqBwB;;;EAhBhC,KAAA,EAAO,WAAA;EAAP;;;;;;EAQA,SAAA,IACE,gBAAA,UACA,OAAA,EAAS,iBAAA,KACN,OAAA,CAAQ,WAAA;EAAA;;;EAKb,SAAA,GAAY,oBAAA;AAAA;AAYd;;;;;;AAAA,cAAa,iBAAA,GACX,OAAA,EAAS,wBAAA,KACR,cAAA;;;AAwNH;;cAAa,gBAAA,GACV,KAAA,GAAQ,GAAA,aAAgB,WAAA,MAClB,gBAAA,aAA2B,OAAA,CAAQ,WAAA"}

package/dist/types/syncPluginKit/createSyncPlugin.d.ts

@@ -0,0 +1,18 @@
+import { CreateSyncPluginOptions } from "./types.js";
+import { Plugin } from "@intlayer/types/plugin";
+
+//#region src/syncPluginKit/createSyncPlugin.d.ts
+/**
+ * Build an Intlayer {@link Plugin} from a transport adapter.
+ *
+ * The factory implements the three plugin hooks once — ingestion
+ * (`loadDictionaries`), content-declaration reformatting (`formatOutput`) and
+ * write-back (`afterBuild`) — so adapters only describe *where* content lives
+ * (filesystem, TMS such as Crowdin, extra CMS…) and codecs only describe the
+ * payload format. Write-back only processes dictionaries whose `location`
+ * matches this plugin instance, so adapters never see foreign content.
+ */
+declare const createSyncPlugin: (options: CreateSyncPluginOptions) => Plugin;
+//#endregion
+export { createSyncPlugin };
+//# sourceMappingURL=createSyncPlugin.d.ts.map

package/dist/types/syncPluginKit/createSyncPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSyncPlugin.d.ts","names":[],"sources":["../../../src/syncPluginKit/createSyncPlugin.ts"],"mappings":";;;;;;AAuCA;;;;;;;;cAAa,gBAAA,GAAoB,OAAA,EAAS,uBAAA,KAA0B,MAAA"}

package/dist/types/syncPluginKit/extractKeyAndLocaleFromPath.d.ts

@@ -0,0 +1,20 @@
+import { Locale } from "@intlayer/types/allLocales";
+
+//#region src/syncPluginKit/extractKeyAndLocaleFromPath.d.ts
+/**
+ * Extract the dictionary key and locale of a file path by matching it against
+ * a mask pattern where `{{__KEY__}}` and `{{__LOCALE__}}` mark the positions
+ * of the key and locale segments.
+ *
+ * Returns `null` when the path does not match the mask, or when the mask
+ * contains no placeholder at all (no named capture group can be produced).
+ * Missing placeholders fall back to `'index'` for the key and to
+ * `defaultLocale` for the locale.
+ */
+declare const extractKeyAndLocaleFromPath: (filePath: string, maskPattern: string, locales: Locale[], defaultLocale: Locale) => {
+  key: string;
+  locale: Locale;
+} | null;
+//#endregion
+export { extractKeyAndLocaleFromPath };
+//# sourceMappingURL=extractKeyAndLocaleFromPath.d.ts.map

package/dist/types/syncPluginKit/extractKeyAndLocaleFromPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractKeyAndLocaleFromPath.d.ts","names":[],"sources":["../../../src/syncPluginKit/extractKeyAndLocaleFromPath.ts"],"mappings":";;;;;AAeA;;;;;;;;cAAa,2BAAA,GACX,QAAA,UACA,WAAA,UACA,OAAA,EAAS,MAAA,IACT,aAAA,EAAe,MAAA;EACZ,GAAA;EAAa,MAAA,EAAQ,MAAA;AAAA"}

package/dist/types/syncPluginKit/filePathPatternHelpers.d.ts

@@ -0,0 +1,16 @@
+import { FilePathPatternContext } from "@intlayer/types/filePathPattern";
+
+//#region src/syncPluginKit/filePathPatternHelpers.d.ts
+/**
+ * Build the context handed to `parseFilePathPattern` from the only two
+ * variables sync plugins resolve: the dictionary key and the locale.
+ *
+ * `FilePathPatternContext` declares extra fields (`fileName`, `extension`,
+ * `format`…) that only apply to content-declaration paths; sync-plugin
+ * patterns never reference them, so this single cast keeps the partial
+ * context in one audited place instead of scattering `as any` at call sites.
+ */
+declare const buildFilePathPatternContext: (key: string, locale?: string) => FilePathPatternContext;
+//#endregion
+export { buildFilePathPatternContext };
+//# sourceMappingURL=filePathPatternHelpers.d.ts.map

package/dist/types/syncPluginKit/filePathPatternHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filePathPatternHelpers.d.ts","names":[],"sources":["../../../src/syncPluginKit/filePathPatternHelpers.ts"],"mappings":";;;;;AAWA;;;;;;;cAAa,2BAAA,GACX,GAAA,UACA,MAAA,cACC,sBAAA"}

package/dist/types/syncPluginKit/index.d.ts

@@ -0,0 +1,6 @@
+import { ContentAdapter, ContentEntry, ContentTarget, CreateSyncPluginOptions, FormatCodec, SyncContent, SyncDirection, SyncPluginContext } from "./types.js";
+import { CreateFileAdapterOptions, FileAdapterDiscovery, createFileAdapter, createFileReader } from "./createFileAdapter.js";
+import { createSyncPlugin } from "./createSyncPlugin.js";
+import { extractKeyAndLocaleFromPath } from "./extractKeyAndLocaleFromPath.js";
+import { buildFilePathPatternContext } from "./filePathPatternHelpers.js";
+export { type ContentAdapter, type ContentEntry, type ContentTarget, type CreateFileAdapterOptions, type CreateSyncPluginOptions, type FileAdapterDiscovery, type FormatCodec, type SyncContent, type SyncDirection, type SyncPluginContext, buildFilePathPatternContext, createFileAdapter, createFileReader, createSyncPlugin, extractKeyAndLocaleFromPath };

package/dist/types/syncPluginKit/types.d.ts

@@ -0,0 +1,149 @@
+import { IntlayerConfig } from "@intlayer/types/config";
+import { DictionaryFormat } from "@intlayer/types/dictionary";
+import { Locale } from "@intlayer/types/allLocales";
+
+//#region src/syncPluginKit/types.d.ts
+/**
+ * Structured dictionary content handled by sync plugins.
+ */
+type SyncContent = Record<string, unknown>;
+/**
+ * Context handed to every {@link ContentAdapter} call.
+ */
+type SyncPluginContext = {
+  configuration: IntlayerConfig;
+};
+/**
+ * One translatable resource discovered in the external system.
+ */
+type ContentEntry = {
+  /** Dictionary key the entry maps to. */key: string; /** Locale of the entry content. */
+  locale: Locale;
+  /**
+   * Transport-specific identifier of the entry: an absolute file path for the
+   * file adapter, a remote resource identifier for API-backed adapters.
+   */
+  uri: string;
+  /**
+   * Absolute file path when the entry lives on the local filesystem.
+   * Leave undefined for remote entries (CMS, TMS…): the generated dictionary
+   * then carries no `filePath` and file-based hooks are skipped for it.
+   */
+  filePath?: string;
+};
+/**
+ * Identifies where content must be written back by a {@link ContentAdapter}.
+ */
+type ContentTarget = {
+  key: string;
+  locale: Locale;
+};
+/**
+ * Transport layer of a sync plugin: where the entries live and how to
+ * enumerate, read and persist them (filesystem, TMS such as Crowdin, extra
+ * CMS…). Format concerns belong to {@link FormatCodec}, orchestration to
+ * `createSyncPlugin`.
+ */
+type ContentAdapter = {
+  /**
+   * Enumerate every entry available in the external system.
+   */
+  list: (context: SyncPluginContext) => Promise<ContentEntry[]>;
+  /**
+   * Read and parse one entry.
+   * Return `undefined` when the entry is missing or unreadable — the plugin
+   * treats it as empty content instead of failing the build.
+   */
+  read: (entry: ContentEntry, context: SyncPluginContext) => Promise<SyncContent | undefined>;
+  /**
+   * Serialize and persist the content of one key/locale back to the external
+   * system. Only called for plugins created with `direction: 'both'`.
+   */
+  write: (target: ContentTarget, content: SyncContent, context: SyncPluginContext) => Promise<void>;
+  /**
+   * Resolve the canonical URI of a key/locale.
+   * Used by the plugin to verify ownership before reformatting a content
+   * declaration in the `formatOutput` hook. Optional: adapters without a
+   * local-file identity (remote systems) can omit it.
+   */
+  resolveUri?: (target: ContentTarget, context: SyncPluginContext) => Promise<string>;
+  /**
+   * Template describing where entries live, with `{{key}}` / `{{locale}}`
+   * markers kept verbatim. Used as the `fill` field of generated dictionaries
+   * so Intlayer knows where translations flow back.
+   */
+  getFillPattern?: (context: SyncPluginContext) => Promise<string>;
+  /**
+   * Human-readable description of the adapter source, used in log messages
+   * (e.g. the file path pattern for the file adapter).
+   */
+  describeSource?: (context: SyncPluginContext) => Promise<string>;
+  /**
+   * Default value for the `splitKeys` behavior when the plugin options do not
+   * set it explicitly (e.g. the file adapter splits when the source pattern
+   * has no `{{key}}` segment).
+   */
+  detectSplitKeys?: () => Promise<boolean>;
+};
+/**
+ * Format layer of a sync plugin: how a raw string payload maps to structured
+ * dictionary content and back (JSON, PO, XLIFF…).
+ */
+type FormatCodec = {
+  /**
+   * Parse a raw payload into dictionary content.
+   * May throw on malformed payloads — callers treat a throw as empty content.
+   */
+  parse: (raw: string) => SyncContent;
+  /**
+   * Serialize dictionary content into the target format.
+   */
+  serialize: (content: SyncContent, context: {
+    locale: Locale;
+  }) => string;
+};
+/**
+ * Direction of the synchronization:
+ * - `pull`: only ingest external content as dictionaries (read-only).
+ * - `both`: ingest and write the merged build output back to the source.
+ */
+type SyncDirection = 'pull' | 'both';
+/**
+ * Options of `createSyncPlugin`.
+ */
+type CreateSyncPluginOptions = {
+  /** Plugin name reported to the Intlayer engine (e.g. `sync-json`). */name: string; /** Transport used to enumerate, read and write entries. */
+  adapter: ContentAdapter;
+  /**
+   * Synchronization direction. Defaults to `'both'`.
+   * With `'pull'` the plugin only implements `loadDictionaries`.
+   */
+  direction?: SyncDirection;
+  /**
+   * Identifier of the plugin instance stored on each generated dictionary.
+   * Dictionaries are routed back to their owning plugin instance through this
+   * value during write-back, so it must be unique per instance.
+   */
+  location: string;
+  /**
+   * Priority of the generated dictionaries when merging with other sources
+   * (`.content` files have priority 0). Defaults to 0.
+   */
+  priority?: number; /** Content format of the dictionaries (e.g. `'icu'`, `'po'`). */
+  format?: DictionaryFormat;
+  /**
+   * Whether each top-level key of an entry becomes its own dictionary instead
+   * of a single dictionary holding the whole entry (the `next-intl` /
+   * `react-intl` namespace model). When omitted, falls back to
+   * {@link ContentAdapter.detectSplitKeys}, then to `false`.
+   */
+  splitKeys?: boolean;
+  /**
+   * Fixed locale applied to every generated dictionary, overriding the locale
+   * discovered per entry.
+   */
+  localeOverride?: Locale;
+};
+//#endregion
+export { ContentAdapter, ContentEntry, ContentTarget, CreateSyncPluginOptions, FormatCodec, SyncContent, SyncDirection, SyncPluginContext };
+//# sourceMappingURL=types.d.ts.map

package/dist/types/syncPluginKit/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/syncPluginKit/types.ts"],"mappings":";;;;;;;AAOA;KAAY,WAAA,GAAc,MAAA;;;;KAKd,iBAAA;EACV,aAAA,EAAe,cAAA;AAAA;;;AAMjB;KAAY,YAAA;0CAEV,GAAA;EAEA,MAAA,EAAQ,MAAA;EAAA;;;;EAKR,GAAA;EAYU;;;;;EANV,QAAA;AAAA;;;AAiBF;KAXY,aAAA;EACV,GAAA;EACA,MAAA,EAAQ,MAAA;AAAA;;;;;;;KASE,cAAA;EAuBC;;;EAnBX,IAAA,GAAO,OAAA,EAAS,iBAAA,KAAsB,OAAA,CAAQ,YAAA;EA+BzC;;;;;EAxBL,IAAA,GACE,KAAA,EAAO,YAAA,EACP,OAAA,EAAS,iBAAA,KACN,OAAA,CAAQ,WAAA;EAyCkB;;;;EAnC/B,KAAA,GACE,MAAA,EAAQ,aAAA,EACR,OAAA,EAAS,WAAA,EACT,OAAA,EAAS,iBAAA,KACN,OAAA;EApBiC;;;;;;EA4BtC,UAAA,IACE,MAAA,EAAQ,aAAA,EACR,OAAA,EAAS,iBAAA,KACN,OAAA;EArBA;;;;;EA4BL,cAAA,IAAkB,OAAA,EAAS,iBAAA,KAAsB,OAAA;EApB/C;;;;EA0BF,cAAA,IAAkB,OAAA,EAAS,iBAAA,KAAsB,OAAA;EAfvC;;;;;EAsBV,eAAA,SAAwB,OAAA;AAAA;;;;;KAOd,WAAA;EAduC;;;;EAmBjD,KAAA,GAAQ,GAAA,aAAgB,WAAA;EALd;;;EAUV,SAAA,GAAY,OAAA,EAAS,WAAA,EAAa,OAAA;IAAW,MAAA,EAAQ,MAAA;EAAA;AAAA;;;;;;KAQ3C,aAAA;;;;KAKA,uBAAA;EAbmD,sEAe7D,IAAA,UAPU;EAUV,OAAA,EAAS,cAAA;;;;AALX;EAWE,SAAA,GAAY,aAAA;;;;;;EAOZ,QAAA;EAuBuB;;;;EAjBvB,QAAA,WAbY;EAgBZ,MAAA,GAAS,gBAAA;EAHT;;;;;;EAWA,SAAA;EAMuB;;;;EAAvB,cAAA,GAAiB,MAAA;AAAA"}

package/dist/types/utils/runParallel/index.d.ts

@@ -1,6 +1,11 @@
 //#region src/utils/runParallel/index.d.ts
 type ParallelHandle = {
-  kill: () => void;
+  /**
+   * Terminate the child and its whole process group.
+   * @param signal Signal to send (default `SIGTERM`). Pass `SIGKILL` to force-kill
+   *   a child that ignores graceful termination.
+   */
+  kill: (signal?: NodeJS.Signals) => void;
   result: Promise<any>;
   commandText: string;
 };

package/dist/types/utils/runParallel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/utils/runParallel/index.ts"],"mappings":";KAIY,cAAA;EACV,IAAA;EACA,MAAA,EAAQ,OAAA;EACR,WAAA;AAAA;;;;;cAOW,WAAA,GAAe,IAAA,yBAA2B,cAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/utils/runParallel/index.ts"],"mappings":";KAIY,cAAA;EAAA;;;;;EAMV,IAAA,GAAO,MAAA,GAAS,MAAA,CAAO,OAAA;EACvB,MAAA,EAAQ,OAAA;EACR,WAAA;AAAA;;;;;cAOW,WAAA,GAAe,IAAA,yBAA2B,cAAA"}

package/dist/types/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","names":[],"sources":["../../src/watcher.ts"],"mappings":";;;;KAuDK,YAAA;EACH,aAAA,GAAgB,cAAA;EAChB,aAAA,GAAgB,uBAAA;EAChB,WAAA;EACA,UAAA;AAAA;AAAA,cAsBW,KAAA,GAAe,OAAA,GAAU,YAAA,KAAY,OAAA;qBAkDN,OAAA;AAAA;AAAA,cAyP/B,qBAAA,GAA+B,OAAA,GAAU,YAAA,KAAY,OAAA"}
+{"version":3,"file":"watcher.d.ts","names":[],"sources":["../../src/watcher.ts"],"mappings":";;;;KAuDK,YAAA;EACH,aAAA,GAAgB,cAAA;EAChB,aAAA,GAAgB,uBAAA;EAChB,WAAA;EACA,UAAA;AAAA;AAAA,cAsBW,KAAA,GAAe,OAAA,GAAU,YAAA,KAAY,OAAA;qBAkDN,OAAA;AAAA;AAAA,cA8P/B,qBAAA,GAA+B,OAAA,GAAU,YAAA,KAAY,OAAA"}

package/dist/types/writeFileIfChanged.d.ts

@@ -1,11 +1,35 @@
 //#region src/writeFileIfChanged.d.ts
+/**
+ * Options for {@link writeFileIfChanged}.
+ */
+type WriteFileIfChangedOptions = {
+  /** Encoding used to turn `data` into bytes. Defaults to `'utf8'`. */encoding?: BufferEncoding; /** Directory to hold the temporary file used for the atomic swap. */
+  tempDir?: string;
+  /**
+   * Write atomically via a temp file + `rename` so readers never observe a
+   * half-written file. This creates a fresh inode on every write, which roughly
+   * doubles the cost of a changed write compared to overwriting in place. Set to
+   * `false` for callers whose consumers tolerate torn reads to write directly.
+   * Defaults to `true`.
+   */
+  atomic?: boolean;
+};
+/**
+ * Write `data` to `path` only when it differs from the file already on disk,
+ * preserving the existing file's permission mode.
+ *
+ * The whole file is read back and byte-compared because the files written here
+ * (dictionaries, entry points, types) are small, so reading beats streaming a
+ * hash. When the content is unchanged the write is skipped entirely, which both
+ * avoids inode churn and prevents downstream watchers from rebuilding.
+ *
+ * @returns `true` when the file was written, `false` when it was already up to date.
+ */
 declare const writeFileIfChanged: (path: string, data: string, {
   encoding,
-  tempDir
-}?: {
-  encoding?: BufferEncoding;
-  tempDir?: string;
-}) => Promise<boolean>;
+  tempDir,
+  atomic
+}?: WriteFileIfChangedOptions) => Promise<boolean>;
 //#endregion
-export { writeFileIfChanged };
+export { WriteFileIfChangedOptions, writeFileIfChanged };
 //# sourceMappingURL=writeFileIfChanged.d.ts.map

package/dist/types/writeFileIfChanged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeFileIfChanged.d.ts","names":[],"sources":["../../src/writeFileIfChanged.ts"],"mappings":";cA2Ba,kBAAA,GACX,IAAA,UACA,IAAA;EACA,QAAA;EAAA;AAAA;EAGK,QAAA,GAAW,cAAA;EAAgB,OAAA;AAAA,MAC/B,OAAA"}
+{"version":3,"file":"writeFileIfChanged.d.ts","names":[],"sources":["../../src/writeFileIfChanged.ts"],"mappings":";;AAoCA;;KAAY,yBAAA;EAEe,qEAAzB,QAAA,GAAW,cAAA,EAAA;EAEX,OAAA;EAQA;;;AAcF;;;;EAdE,MAAA;AAAA;;;;;;;;;;;;cAcW,kBAAA,GACX,IAAA,UACA,IAAA;EACA,QAAA;EAAA,OAAA;EAAA;AAAA,IAA+C,yBAAA,KAC9C,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/engine",
-  "version": "9.0.0-canary.13",
+  "version": "9.0.0-canary.14",
   "private": false,
   "description": "Scans and builds Intlayer declaration files into dictionaries based on Intlayer configuration.",
   "keywords": [
@@ -50,11 +50,21 @@
       "require": "./dist/cjs/cli.cjs",
       "import": "./dist/esm/cli.mjs"
     },
+    "./logConfigDetails": {
+      "types": "./dist/types/logConfigDetails.d.ts",
+      "require": "./dist/cjs/logConfigDetails.cjs",
+      "import": "./dist/esm/logConfigDetails.mjs"
+    },
     "./utils": {
       "types": "./dist/types/utils/index.d.ts",
       "require": "./dist/cjs/utils/index.cjs",
       "import": "./dist/esm/utils/index.mjs"
     },
+    "./syncPluginKit": {
+      "types": "./dist/types/syncPluginKit/index.d.ts",
+      "require": "./dist/cjs/syncPluginKit/index.cjs",
+      "import": "./dist/esm/syncPluginKit/index.mjs"
+    },
     "./listDictionaries": {
       "types": "./dist/types/listDictionariesPath.d.ts",
       "require": "./dist/cjs/listDictionariesPath.cjs",
@@ -86,9 +96,15 @@
       "cli": [
         "./dist/types/cli.d.ts"
       ],
+      "logConfigDetails": [
+        "./dist/types/logConfigDetails.d.ts"
+      ],
       "utils": [
         "./dist/types/utils/index.d.ts"
       ],
+      "syncPluginKit": [
+        "./dist/types/syncPluginKit/index.d.ts"
+      ],
       "listDictionaries": [
         "./dist/types/listDictionariesPath.d.ts"
       ],
@@ -126,13 +142,13 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.7",
-    "@intlayer/api": "9.0.0-canary.13",
-    "@intlayer/config": "9.0.0-canary.13",
-    "@intlayer/core": "9.0.0-canary.13",
-    "@intlayer/dictionaries-entry": "9.0.0-canary.13",
-    "@intlayer/remote-dictionaries-entry": "9.0.0-canary.13",
-    "@intlayer/types": "9.0.0-canary.13",
-    "@intlayer/unmerged-dictionaries-entry": "9.0.0-canary.13",
+    "@intlayer/api": "9.0.0-canary.14",
+    "@intlayer/config": "9.0.0-canary.14",
+    "@intlayer/core": "9.0.0-canary.14",
+    "@intlayer/dictionaries-entry": "9.0.0-canary.14",
+    "@intlayer/remote-dictionaries-entry": "9.0.0-canary.14",
+    "@intlayer/types": "9.0.0-canary.14",
+    "@intlayer/unmerged-dictionaries-entry": "9.0.0-canary.14",
     "@parcel/watcher": "2.5.6",
     "defu": "6.1.7",
     "fast-glob": "3.3.3",