@xylex-group/athena 3.0.2 → 3.0.3

package/dist/cli/index.js

@@ -1,10 +1,766 @@
-import { mkdir, writeFile, stat } from 'fs/promises';
+import { mkdir, writeFile, stat, readFile } from 'fs/promises';
 import { resolve, dirname, posix } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { pathToFileURL } from 'url';
 
 // src/generator/pipeline.ts
 
+// src/generator/artifact-merge.ts
+var IMPORT_RE = /^import\s+(?:type\s+)?(?:\{([^}]*)\}|([A-Za-z_$][\w$]*))\s+from\s+(['"])([^'"]+)\3\s*;?\s*$/gm;
+var DEFINE_EXPORT_RE = /export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(define(?:Database|Registry))\s*\(\s*\{/g;
+var META_EXPORT_RE = /export\s+const\s+__athena_schema_meta\s*=\s*\{/g;
+var KNOWN_META_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "generatedAt",
+  "database",
+  "outputPreset",
+  "outputFormat"
+]);
+function detectNewline(source) {
+  return source.includes("\r\n") ? "\r\n" : "\n";
+}
+function detectStyle(source) {
+  const newline = detectNewline(source);
+  const single = (source.match(/'/g) ?? []).length;
+  const double = (source.match(/"/g) ?? []).length;
+  const quote = double > single ? '"' : "'";
+  const importLines = source.split(/\r?\n/).filter((line) => line.trimStart().startsWith("import "));
+  const semicolons = importLines.length > 0 ? importLines.filter((line) => line.trimEnd().endsWith(";")).length >= importLines.length / 2 : false;
+  const objectLines = source.split(/\r?\n/).map((line) => line.trim()).filter((line) => /^[A-Za-z0-9_'"]+\s*:\s*.+/.test(line));
+  const trailingComma = objectLines.length > 0 ? objectLines.filter((line) => line.endsWith(",")).length >= Math.ceil(objectLines.length / 2) : true;
+  const indentMatch = source.match(/\n([ \t]+)\S/);
+  const indent = indentMatch?.[1] ?? "  ";
+  return { quote, semicolons, trailingComma, indent, newline };
+}
+function quoteString(value, quote) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(new RegExp(quote, "g"), `\\${quote}`);
+  return `${quote}${escaped}${quote}`;
+}
+function parseNamedImports(source) {
+  const imports = [];
+  IMPORT_RE.lastIndex = 0;
+  let match;
+  while ((match = IMPORT_RE.exec(source)) !== null) {
+    const named = match[1];
+    const defaultName = match[2];
+    const module = match[4];
+    const names = named ? named.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+      const alias = part.split(/\s+as\s+/);
+      return (alias[1] ?? alias[0]).trim();
+    }) : defaultName ? [defaultName] : [];
+    imports.push({
+      names,
+      module,
+      raw: match[0],
+      start: match.index,
+      end: match.index + match[0].length
+    });
+  }
+  return imports;
+}
+function findMatchingBrace(source, openIndex) {
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inTemplate = false;
+  let escaped = false;
+  for (let i = openIndex; i < source.length; i += 1) {
+    const ch = source[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\" && (inSingle || inDouble || inTemplate)) {
+      escaped = true;
+      continue;
+    }
+    if (!inDouble && !inTemplate && ch === "'") {
+      inSingle = !inSingle;
+      continue;
+    }
+    if (!inSingle && !inTemplate && ch === '"') {
+      inDouble = !inDouble;
+      continue;
+    }
+    if (!inSingle && !inDouble && ch === "`") {
+      inTemplate = !inTemplate;
+      continue;
+    }
+    if (inSingle || inDouble || inTemplate) {
+      continue;
+    }
+    if (ch === "{") {
+      depth += 1;
+    } else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+function parseObjectEntries(body) {
+  const entries = [];
+  const lines = body.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("/*")) {
+      continue;
+    }
+    const withoutComma = trimmed.endsWith(",") ? trimmed.slice(0, -1).trimEnd() : trimmed;
+    const match = withoutComma.match(/^([A-Za-z_$][\w$]*|['"][^'"]+['"])\s*:\s*(.+)$/);
+    if (!match) {
+      continue;
+    }
+    const keyRaw = match[1];
+    const key = keyRaw.startsWith("'") || keyRaw.startsWith('"') ? keyRaw.slice(1, -1) : keyRaw;
+    entries.push({
+      key,
+      value: match[2].trim(),
+      raw: trimmed
+    });
+  }
+  return entries;
+}
+function parseDefineBlocks(source) {
+  const blocks = [];
+  DEFINE_EXPORT_RE.lastIndex = 0;
+  let match;
+  while ((match = DEFINE_EXPORT_RE.exec(source)) !== null) {
+    const exportName = match[1];
+    const callName = match[2];
+    const openBrace = match.index + match[0].lastIndexOf("{");
+    const closeBrace = findMatchingBrace(source, openBrace);
+    if (closeBrace < 0) {
+      continue;
+    }
+    const body = source.slice(openBrace + 1, closeBrace);
+    const fullEnd = (() => {
+      let i = closeBrace + 1;
+      while (i < source.length && /\s/.test(source[i])) i += 1;
+      if (source[i] === ")") i += 1;
+      while (i < source.length && /\s/.test(source[i])) i += 1;
+      if (source[i] === ";") i += 1;
+      return i;
+    })();
+    blocks.push({
+      kind: callName === "defineDatabase" ? "database" : "registry",
+      exportName,
+      callName,
+      entries: parseObjectEntries(body),
+      bodyStart: openBrace + 1,
+      bodyEnd: closeBrace,
+      fullStart: match.index,
+      fullEnd,
+      raw: source.slice(match.index, fullEnd)
+    });
+  }
+  return blocks;
+}
+function parseMetaBlock(source) {
+  META_EXPORT_RE.lastIndex = 0;
+  const match = META_EXPORT_RE.exec(source);
+  if (!match) {
+    return void 0;
+  }
+  const openBrace = match.index + match[0].lastIndexOf("{");
+  const closeBrace = findMatchingBrace(source, openBrace);
+  if (closeBrace < 0) {
+    return void 0;
+  }
+  let fullEnd = closeBrace + 1;
+  const after = source.slice(fullEnd);
+  const asConst = after.match(/^\s*as\s+const\s*;?/);
+  if (asConst) {
+    fullEnd += asConst[0].length;
+  } else if (source[fullEnd] === ";") {
+    fullEnd += 1;
+  }
+  return {
+    entries: parseObjectEntries(source.slice(openBrace + 1, closeBrace)),
+    bodyStart: openBrace + 1,
+    bodyEnd: closeBrace,
+    fullStart: match.index,
+    fullEnd,
+    raw: source.slice(match.index, fullEnd)
+  };
+}
+function hasImportBinding(imports, name, module) {
+  return imports.some(
+    (item) => item.names.includes(name) && (module === void 0)
+  );
+}
+function findImportForName(imports, name) {
+  return imports.find((item) => item.names.includes(name));
+}
+function normalizeModulePath(modulePath) {
+  return modulePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\.ts$/, "");
+}
+function formatImport(names, modulePath, style) {
+  const body = `import { ${names.join(", ")} } from ${quoteString(modulePath, style.quote)}`;
+  return style.semicolons ? `${body};` : body;
+}
+function formatObjectEntry(key, value, style, isLast) {
+  const needsQuote = !/^[A-Za-z_$][\w$]*$/.test(key);
+  const renderedKey = needsQuote ? quoteString(key, style.quote) : key;
+  const comma = !isLast || style.trailingComma ? "," : "";
+  return `${style.indent}${renderedKey}: ${value}${comma}`;
+}
+function replaceRange(source, start, end, insertion) {
+  return source.slice(0, start) + insertion + source.slice(end);
+}
+function collectDuplicateKeys(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const dupes = [];
+  for (const entry of entries) {
+    if (seen.has(entry.key)) {
+      dupes.push(entry.key);
+    }
+    seen.add(entry.key);
+  }
+  return dupes;
+}
+function collectDuplicateImportBindings(imports) {
+  const seen = /* @__PURE__ */ new Set();
+  const dupes = [];
+  for (const item of imports) {
+    for (const name of item.names) {
+      if (seen.has(name)) {
+        dupes.push(name);
+      }
+      seen.add(name);
+    }
+  }
+  return dupes;
+}
+function lintArtifactSource(source, kind) {
+  const errors = [];
+  const imports = parseNamedImports(source);
+  const dupImports = collectDuplicateImportBindings(imports);
+  if (dupImports.length > 0) {
+    errors.push(`duplicate import bindings: ${dupImports.join(", ")}`);
+  }
+  const blocks = parseDefineBlocks(source).filter((block2) => block2.kind === kind);
+  if (blocks.length === 0) {
+    errors.push(`missing export const \u2026 = define${kind === "database" ? "Database" : "Registry"}({\u2026})`);
+    return errors;
+  }
+  if (blocks.length > 1) {
+    errors.push(`multiple define${kind === "database" ? "Database" : "Registry"} exports found`);
+  }
+  const block = blocks[0];
+  const dupKeys = collectDuplicateKeys(block.entries);
+  if (dupKeys.length > 0) {
+    errors.push(`duplicate object keys: ${dupKeys.join(", ")}`);
+  }
+  for (const entry of block.entries) {
+    const valueId = entry.value.match(/^[A-Za-z_$][\w$]*$/)?.[0];
+    if (valueId && !hasImportBinding(imports, valueId) && valueId !== block.exportName) {
+      if (!source.includes(`const ${valueId}`) && !source.includes(`function ${valueId}`)) {
+        errors.push(`value "${valueId}" for key "${entry.key}" is not imported`);
+      }
+    }
+  }
+  if (kind === "database" && !hasImportBinding(imports, "defineDatabase")) {
+    errors.push("missing defineDatabase import");
+  }
+  if (kind === "registry" && !hasImportBinding(imports, "defineRegistry")) {
+    errors.push("missing defineRegistry import");
+  }
+  return errors;
+}
+function preservedCustomUnits(existing, generated, kind) {
+  const custom = [];
+  const existingImports = parseNamedImports(existing);
+  const generatedImports = parseNamedImports(generated);
+  const generatedModules = new Set(generatedImports.map((item) => normalizeModulePath(item.module)));
+  const generatedNames = new Set(generatedImports.flatMap((item) => item.names));
+  for (const item of existingImports) {
+    const moduleNorm = normalizeModulePath(item.module);
+    if (moduleNorm.includes("@xylex-group/athena")) {
+      continue;
+    }
+    const unexpectedNames = item.names.filter((name) => !generatedNames.has(name));
+    if (unexpectedNames.length > 0 && !generatedModules.has(moduleNorm)) {
+      custom.push(`import { ${unexpectedNames.join(", ")} } from '${item.module}'`);
+    } else if (unexpectedNames.length > 0) {
+      custom.push(`import binding(s): ${unexpectedNames.join(", ")}`);
+    }
+  }
+  const existingBlocks = parseDefineBlocks(existing).filter((block) => block.kind === kind);
+  const generatedBlocks = parseDefineBlocks(generated).filter((block) => block.kind === kind);
+  const generatedKeys = new Set(generatedBlocks[0]?.entries.map((entry) => entry.key) ?? []);
+  for (const entry of existingBlocks[0]?.entries ?? []) {
+    if (!generatedKeys.has(entry.key)) {
+      custom.push(`${kind} entry: ${entry.key}: ${entry.value}`);
+    }
+  }
+  if (kind === "registry") {
+    const existingMeta = parseMetaBlock(existing);
+    const generatedMeta = parseMetaBlock(generated);
+    const generatedMetaKeys = new Set(generatedMeta?.entries.map((entry) => entry.key) ?? []);
+    for (const entry of existingMeta?.entries ?? []) {
+      if (!generatedMetaKeys.has(entry.key) && !KNOWN_META_KEYS.has(entry.key)) {
+        custom.push(`meta entry: ${entry.key}: ${entry.value}`);
+      }
+    }
+  }
+  const exportConstRe = /^export\s+const\s+([A-Za-z_$][\w$]*)\b/gm;
+  const generatedExports = /* @__PURE__ */ new Set();
+  let match;
+  exportConstRe.lastIndex = 0;
+  while ((match = exportConstRe.exec(generated)) !== null) {
+    generatedExports.add(match[1]);
+  }
+  exportConstRe.lastIndex = 0;
+  while ((match = exportConstRe.exec(existing)) !== null) {
+    if (!generatedExports.has(match[1]) && match[1] !== "__athena_schema_meta") {
+      custom.push(`export const ${match[1]}`);
+    }
+  }
+  return custom;
+}
+function insertImportAfterPackageImports(source, importLine, style) {
+  const imports = parseNamedImports(source);
+  if (imports.length === 0) {
+    return `${importLine}${style.newline}${source}`;
+  }
+  let anchor = imports[imports.length - 1];
+  for (let i = imports.length - 1; i >= 0; i -= 1) {
+    if (imports[i].module.startsWith(".")) {
+      anchor = imports[i];
+      break;
+    }
+  }
+  const insertAt = anchor.end;
+  const before = source.slice(0, insertAt);
+  const after = source.slice(insertAt);
+  const needsLeadingNl = !before.endsWith("\n");
+  const prefix = needsLeadingNl ? style.newline : "";
+  return `${before}${prefix}${importLine}${after.startsWith("\n") || after.startsWith("\r\n") ? "" : style.newline}${after}`;
+}
+function rewriteObjectBody(entries, style) {
+  if (entries.length === 0) {
+    return style.newline;
+  }
+  const lines = entries.map(
+    (entry, index) => formatObjectEntry(entry.key, entry.value, style, index === entries.length - 1)
+  );
+  return `${style.newline}${lines.join(style.newline)}${style.newline}`;
+}
+function mergeDatabaseArtifact(existing, generated) {
+  const style = detectStyle(existing);
+  const generatedStyle = detectStyle(generated);
+  const effectiveStyle = {
+    ...style,
+    // Prefer existing fingerprint; fall back to generated if existing is empty-ish
+    quote: existing.includes('"') || existing.includes("'") ? style.quote : generatedStyle.quote
+  };
+  const generatedImports = parseNamedImports(generated);
+  const existingBlocks = parseDefineBlocks(existing).filter((block) => block.kind === "database");
+  const generatedBlocks = parseDefineBlocks(generated).filter((block) => block.kind === "database");
+  if (existingBlocks.length === 0 || generatedBlocks.length === 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-unparseable",
+      added: [],
+      preservedCustom: [],
+      conflicts: [],
+      lintErrors: [],
+      detail: "could not locate defineDatabase({\u2026}) export for merge"
+    };
+  }
+  const generatedBlock = generatedBlocks[0];
+  const conflicts = [];
+  const added = [];
+  let next = existing;
+  if (!hasImportBinding(parseNamedImports(next), "defineDatabase")) {
+    const pkgImport = generatedImports.find((item) => item.names.includes("defineDatabase"));
+    if (pkgImport) {
+      const line = formatImport(["defineDatabase"], pkgImport.module, effectiveStyle);
+      next = insertImportAfterPackageImports(next, line, effectiveStyle);
+      added.push("import defineDatabase");
+    }
+  }
+  let workingImports = parseNamedImports(next);
+  let workingBlocks = parseDefineBlocks(next).filter((block) => block.kind === "database");
+  let workingBlock = workingBlocks[0];
+  const entryMap = new Map(workingBlock.entries.map((entry) => [entry.key, entry]));
+  for (const desired of generatedBlock.entries) {
+    const existingEntry = entryMap.get(desired.key);
+    if (existingEntry) {
+      if (existingEntry.value !== desired.value) {
+        conflicts.push(
+          `key "${desired.key}" maps to ${existingEntry.value} (existing) vs ${desired.value} (generated)`
+        );
+      }
+      continue;
+    }
+    const desiredImport = generatedImports.find((item) => item.names.includes(desired.value));
+    if (desiredImport) {
+      const existingForName = findImportForName(workingImports, desired.value);
+      if (existingForName) {
+        if (normalizeModulePath(existingForName.module) !== normalizeModulePath(desiredImport.module)) {
+          conflicts.push(
+            `binding "${desired.value}" imported from '${existingForName.module}' vs '${desiredImport.module}'`
+          );
+          continue;
+        }
+      } else {
+        const line = formatImport([desired.value], desiredImport.module, effectiveStyle);
+        next = insertImportAfterPackageImports(next, line, effectiveStyle);
+        added.push(`import ${desired.value}`);
+        workingImports = parseNamedImports(next);
+      }
+    }
+    workingBlocks = parseDefineBlocks(next).filter((block) => block.kind === "database");
+    workingBlock = workingBlocks[0];
+    const nextEntries = [...workingBlock.entries, { key: desired.key, value: desired.value, raw: "" }];
+    const body = rewriteObjectBody(nextEntries, effectiveStyle);
+    next = replaceRange(next, workingBlock.bodyStart, workingBlock.bodyEnd, body);
+    entryMap.set(desired.key, { key: desired.key, value: desired.value, raw: "" });
+    added.push(`database entry: ${desired.key}`);
+  }
+  if (conflicts.length > 0 && added.length === 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-conflict",
+      added: [],
+      preservedCustom: preservedCustomUnits(existing, generated, "database"),
+      conflicts,
+      lintErrors: [],
+      detail: conflicts.join("; ")
+    };
+  }
+  const lintErrors = lintArtifactSource(next, "database");
+  if (lintErrors.length > 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-lint-failed",
+      added,
+      preservedCustom: preservedCustomUnits(existing, generated, "database"),
+      conflicts,
+      lintErrors,
+      detail: lintErrors.join("; ")
+    };
+  }
+  const preservedCustom = preservedCustomUnits(next, generated, "database");
+  if (next === existing || next.replace(/\r\n/g, "\n") === existing.replace(/\r\n/g, "\n")) {
+    return {
+      action: "unchanged",
+      content: existing,
+      skipReason: "already-current",
+      added: [],
+      preservedCustom,
+      conflicts,
+      lintErrors: [],
+      detail: conflicts.length > 0 ? conflicts.join("; ") : void 0
+    };
+  }
+  return {
+    action: "write",
+    content: next.endsWith("\n") ? next : `${next}${effectiveStyle.newline}`,
+    writeReason: "merged",
+    added,
+    preservedCustom,
+    conflicts,
+    lintErrors: []
+  };
+}
+function mergeMetaFields(existingMeta, generatedMeta) {
+  const added = [];
+  if (!generatedMeta) {
+    return { entries: existingMeta?.entries ?? [], changed: false, added };
+  }
+  if (!existingMeta) {
+    return {
+      entries: generatedMeta.entries,
+      changed: true,
+      added: generatedMeta.entries.map((entry) => `meta entry: ${entry.key}`)
+    };
+  }
+  const map = new Map(existingMeta.entries.map((entry) => [entry.key, entry]));
+  let changed = false;
+  for (const desired of generatedMeta.entries) {
+    const current = map.get(desired.key);
+    if (!current) {
+      map.set(desired.key, desired);
+      added.push(`meta entry: ${desired.key}`);
+      changed = true;
+      continue;
+    }
+    if (KNOWN_META_KEYS.has(desired.key) && current.value !== desired.value) {
+      map.set(desired.key, desired);
+      added.push(`meta refresh: ${desired.key}`);
+      changed = true;
+    }
+  }
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of existingMeta.entries) {
+    const next = map.get(entry.key);
+    if (next) {
+      ordered.push(next);
+      seen.add(entry.key);
+    }
+  }
+  for (const entry of generatedMeta.entries) {
+    if (!seen.has(entry.key)) {
+      const next = map.get(entry.key);
+      if (next) {
+        ordered.push(next);
+        seen.add(entry.key);
+      }
+    }
+  }
+  for (const [key, entry] of map) {
+    if (!seen.has(key)) {
+      ordered.push(entry);
+    }
+  }
+  return { entries: ordered, changed, added };
+}
+function mergeRegistryArtifact(existing, generated) {
+  const style = detectStyle(existing);
+  const effectiveStyle = style;
+  const generatedImports = parseNamedImports(generated);
+  const existingBlocks = parseDefineBlocks(existing).filter((block) => block.kind === "registry");
+  const generatedBlocks = parseDefineBlocks(generated).filter((block) => block.kind === "registry");
+  if (existingBlocks.length === 0 || generatedBlocks.length === 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-unparseable",
+      added: [],
+      preservedCustom: [],
+      conflicts: [],
+      lintErrors: [],
+      detail: "could not locate defineRegistry({\u2026}) export for merge"
+    };
+  }
+  const existingBlock = existingBlocks[0];
+  const generatedBlock = generatedBlocks[0];
+  const conflicts = [];
+  const added = [];
+  let next = existing;
+  if (!hasImportBinding(parseNamedImports(next), "defineRegistry")) {
+    const pkgImport = generatedImports.find((item) => item.names.includes("defineRegistry"));
+    if (pkgImport) {
+      next = insertImportAfterPackageImports(
+        next,
+        formatImport(["defineRegistry"], pkgImport.module, effectiveStyle),
+        effectiveStyle
+      );
+      added.push("import defineRegistry");
+    }
+  }
+  const preferredDbValue = existingBlock.entries[0]?.value ?? generatedBlock.entries[0]?.value;
+  const generatedDbImport = generatedImports.find((item) => item.names.includes(generatedBlock.entries[0]?.value ?? "")) ?? generatedImports.find((item) => item.module.startsWith("."));
+  if (preferredDbValue && generatedDbImport) {
+    const existingForName = findImportForName(parseNamedImports(next), preferredDbValue);
+    if (!existingForName) {
+      const modulePath = generatedDbImport.module;
+      const importName = findImportForName(generatedImports, preferredDbValue)?.names[0] ?? generatedBlock.entries[0]?.value ?? preferredDbValue;
+      if (!hasImportBinding(parseNamedImports(next), importName)) {
+        next = insertImportAfterPackageImports(
+          next,
+          formatImport([importName], modulePath, effectiveStyle),
+          effectiveStyle
+        );
+        added.push(`import ${importName}`);
+      }
+    } else if (normalizeModulePath(existingForName.module) !== normalizeModulePath(generatedDbImport.module)) {
+      conflicts.push(
+        `binding "${preferredDbValue}" imported from '${existingForName.module}' vs '${generatedDbImport.module}'`
+      );
+    }
+  }
+  let workingBlocks = parseDefineBlocks(next).filter((block) => block.kind === "registry");
+  let workingBlock = workingBlocks[0];
+  const entryMap = new Map(workingBlock.entries.map((entry) => [entry.key, entry]));
+  for (const desired of generatedBlock.entries) {
+    const existingEntry = entryMap.get(desired.key);
+    if (existingEntry) {
+      continue;
+    }
+    const dbImport = parseNamedImports(next).find(
+      (item) => item.module.startsWith(".") && item.names.some((name) => name !== "defineRegistry")
+    );
+    const value = dbImport?.names[0] ?? desired.value;
+    const nextEntries = [...workingBlock.entries, { key: desired.key, value, raw: "" }];
+    const body = rewriteObjectBody(nextEntries, effectiveStyle);
+    next = replaceRange(next, workingBlock.bodyStart, workingBlock.bodyEnd, body);
+    entryMap.set(desired.key, { key: desired.key, value, raw: "" });
+    added.push(`registry entry: ${desired.key}`);
+    workingBlocks = parseDefineBlocks(next).filter((block) => block.kind === "registry");
+    workingBlock = workingBlocks[0];
+  }
+  const existingMeta = parseMetaBlock(next);
+  const generatedMeta = parseMetaBlock(generated);
+  const structuralAdded = added.length > 0;
+  if (generatedMeta) {
+    if (!existingMeta) {
+      const blocks = parseDefineBlocks(next).filter((block) => block.kind === "registry");
+      const insertAt = blocks[0]?.fullStart ?? next.length;
+      const metaBody = rewriteObjectBody(generatedMeta.entries, effectiveStyle);
+      const metaBlock = `export const __athena_schema_meta = {${metaBody}} as const${effectiveStyle.semicolons ? ";" : ""}${effectiveStyle.newline}${effectiveStyle.newline}`;
+      next = replaceRange(next, insertAt, insertAt, metaBlock);
+      added.push("__athena_schema_meta");
+    } else {
+      const desiredEntries = structuralAdded ? generatedMeta.entries : generatedMeta.entries.filter((entry) => {
+        return !existingMeta.entries.some((current) => current.key === entry.key);
+      });
+      if (structuralAdded) {
+        const merged = mergeMetaFields(existingMeta, generatedMeta);
+        if (merged.changed) {
+          const metaNow = parseMetaBlock(next);
+          if (metaNow) {
+            const body = rewriteObjectBody(merged.entries, effectiveStyle);
+            next = replaceRange(next, metaNow.bodyStart, metaNow.bodyEnd, body);
+            added.push(...merged.added);
+          }
+        }
+      } else if (desiredEntries.length > 0) {
+        const map = new Map(existingMeta.entries.map((entry) => [entry.key, entry]));
+        for (const entry of desiredEntries) {
+          map.set(entry.key, entry);
+          added.push(`meta entry: ${entry.key}`);
+        }
+        const ordered = [
+          ...existingMeta.entries.map((entry) => map.get(entry.key)),
+          ...desiredEntries.filter((entry) => !existingMeta.entries.some((e) => e.key === entry.key))
+        ];
+        const metaNow = parseMetaBlock(next);
+        if (metaNow) {
+          const body = rewriteObjectBody(ordered, effectiveStyle);
+          next = replaceRange(next, metaNow.bodyStart, metaNow.bodyEnd, body);
+        }
+      }
+    }
+  }
+  if (conflicts.length > 0 && added.length === 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-conflict",
+      added: [],
+      preservedCustom: preservedCustomUnits(existing, generated, "registry"),
+      conflicts,
+      lintErrors: [],
+      detail: conflicts.join("; ")
+    };
+  }
+  const lintErrors = lintArtifactSource(next, "registry");
+  if (lintErrors.length > 0) {
+    return {
+      action: "skip",
+      skipReason: "merge-lint-failed",
+      added,
+      preservedCustom: preservedCustomUnits(existing, generated, "registry"),
+      conflicts,
+      lintErrors,
+      detail: lintErrors.join("; ")
+    };
+  }
+  const preservedCustom = preservedCustomUnits(next, generated, "registry");
+  if (next.replace(/\r\n/g, "\n") === existing.replace(/\r\n/g, "\n")) {
+    return {
+      action: "unchanged",
+      content: existing,
+      skipReason: "already-current",
+      added: [],
+      preservedCustom,
+      conflicts,
+      lintErrors: []
+    };
+  }
+  return {
+    action: "write",
+    content: next.endsWith("\n") ? next : `${next}${effectiveStyle.newline}`,
+    writeReason: "merged",
+    added,
+    preservedCustom,
+    conflicts,
+    lintErrors: []
+  };
+}
+function mergeProtectedArtifact(kind, existing, generated, policy) {
+  if (policy === "overwrite") {
+    if (existing.replace(/\r\n/g, "\n") === generated.replace(/\r\n/g, "\n")) {
+      return {
+        action: "unchanged",
+        content: existing,
+        skipReason: "already-current",
+        added: [],
+        preservedCustom: [],
+        conflicts: [],
+        lintErrors: []
+      };
+    }
+    return {
+      action: "write",
+      content: generated,
+      writeReason: "overwritten",
+      added: ["full overwrite"],
+      preservedCustom: [],
+      conflicts: [],
+      lintErrors: []
+    };
+  }
+  if (policy === "skip") {
+    return {
+      action: "skip",
+      skipReason: "protected-existing-file",
+      added: [],
+      preservedCustom: preservedCustomUnits(existing, generated, kind),
+      conflicts: [],
+      lintErrors: [],
+      detail: "artifactWrite policy is skip"
+    };
+  }
+  return kind === "database" ? mergeDatabaseArtifact(existing, generated) : mergeRegistryArtifact(existing, generated);
+}
+function resolveArtifactWritePlan(file, existingContent, policy) {
+  if (existingContent === null) {
+    return {
+      action: "write",
+      content: file.content,
+      writeReason: "created",
+      added: ["created"],
+      preservedCustom: [],
+      conflicts: [],
+      lintErrors: []
+    };
+  }
+  if (file.kind === "model" || file.kind === "schema" || policy === "always") {
+    if (existingContent.replace(/\r\n/g, "\n") === file.content.replace(/\r\n/g, "\n")) {
+      return {
+        action: "unchanged",
+        content: existingContent,
+        skipReason: "already-current",
+        added: [],
+        preservedCustom: [],
+        conflicts: [],
+        lintErrors: []
+      };
+    }
+    return {
+      action: "write",
+      content: file.content,
+      writeReason: existingContent ? "overwritten" : "created",
+      added: ["overwritten"],
+      preservedCustom: [],
+      conflicts: [],
+      lintErrors: []
+    };
+  }
+  return mergeProtectedArtifact(
+    file.kind,
+    existingContent,
+    file.content,
+    policy
+  );
+}
+
 // src/utils/slugify.ts
 function slugify(input) {
   return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
@@ -781,6 +1537,12 @@ var ATHENA_DIRECT_TARGETS = {
 };
 var DEFAULT_OUTPUT_FORMAT = "table-builder";
 var DEFAULT_OUTPUT_PRESET = "athena-direct";
+var DEFAULT_ARTIFACT_WRITE_POLICY = "merge";
+var ARTIFACT_WRITE_POLICIES = /* @__PURE__ */ new Set([
+  "merge",
+  "skip",
+  "overwrite"
+]);
 var DEFAULT_NAMING = {
   modelType: "pascal",
   modelConst: "camel",
@@ -1060,6 +1822,23 @@ function normalizeFilterConfig(input) {
     excludeTables: normalizeTableSelection(input?.excludeTables)
   };
 }
+function normalizeArtifactWritePolicy(value, fieldName) {
+  if (value === void 0 || value === null || value === "") {
+    return DEFAULT_ARTIFACT_WRITE_POLICY;
+  }
+  if (typeof value === "string" && ARTIFACT_WRITE_POLICIES.has(value)) {
+    return value;
+  }
+  throw new Error(
+    `Invalid output.artifactWrite.${fieldName}: expected one of merge | skip | overwrite, received ${JSON.stringify(value)}.`
+  );
+}
+function normalizeArtifactWriteConfig(input) {
+  return {
+    database: normalizeArtifactWritePolicy(input?.database, "database"),
+    registry: normalizeArtifactWritePolicy(input?.registry, "registry")
+  };
+}
 function normalizeOutputConfig(output) {
   const preset = output?.preset ?? DEFAULT_OUTPUT_PRESET;
   return {
@@ -1071,7 +1850,8 @@ function normalizeOutputConfig(output) {
     },
     placeholderMap: {
       ...output?.placeholderMap ?? {}
-    }
+    },
+    artifactWrite: normalizeArtifactWriteConfig(output?.artifactWrite)
   };
 }
 function normalizeProviderConfig(provider) {
@@ -3288,7 +4068,7 @@ function buildAthenaGatewayUrl(baseUrl, path) {
 
 // package.json
 var package_default = {
-  version: "3.0.2"
+  version: "3.0.3"
 };
 
 // src/sdk-version.ts
@@ -11743,9 +12523,6 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
 }
 
 // src/generator/pipeline.ts
-function canOverwriteArtifact(file) {
-  return file.kind === "model" || file.kind === "schema";
-}
 async function fileExists(path) {
   try {
     await stat(path);
@@ -11754,25 +12531,70 @@ async function fileExists(path) {
     return false;
   }
 }
-async function writeArtifacts(files, cwd) {
+async function readExisting(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function policyForArtifact(file, config) {
+  if (file.kind === "model" || file.kind === "schema") {
+    return "always";
+  }
+  if (file.kind === "database") {
+    return config.output.artifactWrite.database;
+  }
+  return config.output.artifactWrite.registry;
+}
+async function writeArtifacts(files, cwd, config, dryRun) {
   const writtenFiles = [];
+  const writtenDetails = [];
   const skippedFiles = [];
   for (const file of files) {
     const absolutePath = resolve(cwd, file.path);
-    if (!canOverwriteArtifact(file) && await fileExists(absolutePath)) {
+    const exists = await fileExists(absolutePath);
+    const existingContent = exists ? await readExisting(absolutePath) : null;
+    const policy = policyForArtifact(file, config);
+    const plan = resolveArtifactWritePlan(file, existingContent, policy);
+    if (plan.action === "skip" || plan.action === "unchanged") {
       skippedFiles.push({
         kind: file.kind,
         path: file.path,
-        reason: "protected-existing-file"
+        reason: plan.skipReason ?? "already-current",
+        detail: plan.detail,
+        preservedCustom: plan.preservedCustom.length > 0 ? plan.preservedCustom : void 0,
+        conflicts: plan.conflicts.length > 0 ? plan.conflicts : void 0,
+        lintErrors: plan.lintErrors.length > 0 ? plan.lintErrors : void 0
       });
       continue;
     }
-    await mkdir(dirname(absolutePath), { recursive: true });
-    await writeFile(absolutePath, file.content, "utf8");
+    if (!plan.content || !plan.writeReason) {
+      skippedFiles.push({
+        kind: file.kind,
+        path: file.path,
+        reason: "merge-lint-failed",
+        detail: "merge produced no content",
+        lintErrors: plan.lintErrors
+      });
+      continue;
+    }
+    if (!dryRun) {
+      await mkdir(dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, plan.content, "utf8");
+    }
     writtenFiles.push(file.path);
+    writtenDetails.push({
+      kind: file.kind,
+      path: file.path,
+      reason: plan.writeReason,
+      added: plan.added.length > 0 ? plan.added : void 0,
+      preservedCustom: plan.preservedCustom.length > 0 ? plan.preservedCustom : void 0
+    });
   }
   return {
     writtenFiles,
+    writtenDetails,
     skippedFiles
   };
 }
@@ -11788,12 +12610,18 @@ async function runSchemaGenerator(options = {}) {
     schemas: resolveProviderSchemas(config.provider)
   });
   const generated = generateArtifactsFromSnapshot(snapshot, config);
-  const writeResult = options.dryRun ? { writtenFiles: [], skippedFiles: [] } : await writeArtifacts(generated.files, cwd);
+  const writeResult = await writeArtifacts(
+    generated.files,
+    cwd,
+    config,
+    options.dryRun === true
+  );
   return {
     ...generated,
     configPath,
     config,
     writtenFiles: writeResult.writtenFiles,
+    writtenDetails: writeResult.writtenDetails,
     skippedFiles: writeResult.skippedFiles
   };
 }
@@ -12083,10 +12911,52 @@ function logCliError(error, errorLog = console.error) {
 }
 function formatSkippedArtifactLine(artifact) {
   if (artifact.reason === "protected-existing-file") {
-    return ` [skip] ${artifact.path} (existing ${artifact.kind} artifacts are protected from overwrite; delete or retarget the file to regenerate it)`;
+    return ` [skip] ${artifact.path} (existing ${artifact.kind} artifacts are protected from overwrite; set output.artifactWrite.${artifact.kind}="merge"|"overwrite" or delete/retarget the file)`;
+  }
+  if (artifact.reason === "already-current") {
+    const custom = artifact.preservedCustom && artifact.preservedCustom.length > 0 ? `; preserves ${artifact.preservedCustom.length} non-generated unit(s)` : "";
+    return ` [ok] ${artifact.path} (already current${custom})`;
+  }
+  if (artifact.reason === "merge-conflict") {
+    return ` [skip] ${artifact.path} (merge conflict: ${artifact.detail ?? "see conflicts"}; file left unchanged)`;
+  }
+  if (artifact.reason === "merge-lint-failed") {
+    return ` [skip] ${artifact.path} (merge lint failed: ${artifact.detail ?? "invalid merged TypeScript"}; file left unchanged)`;
+  }
+  if (artifact.reason === "merge-unparseable") {
+    return ` [skip] ${artifact.path} (existing ${artifact.kind} artifact is not mergeable; delete, retarget, or set output.artifactWrite.${artifact.kind}="overwrite")`;
   }
   return ` [skip] ${artifact.path}`;
 }
+function formatWrittenArtifactLine(artifact) {
+  if (artifact.reason === "merged") {
+    const added = artifact.added && artifact.added.length > 0 ? ` +${artifact.added.length}: ${artifact.added.slice(0, 4).join(", ")}${artifact.added.length > 4 ? "\u2026" : ""}` : "";
+    const custom = artifact.preservedCustom && artifact.preservedCustom.length > 0 ? `; preserves ${artifact.preservedCustom.length} non-generated unit(s)` : "";
+    return ` [merge] ${artifact.path}${added}${custom}`;
+  }
+  if (artifact.reason === "overwritten") {
+    return ` [write] ${artifact.path} (overwritten)`;
+  }
+  return ` - ${artifact.path}`;
+}
+function formatCustomPreserveWarnings(result) {
+  const lines = [];
+  for (const artifact of result.writtenDetails) {
+    if (artifact.preservedCustom && artifact.preservedCustom.length > 0) {
+      lines.push(
+        ` [warn] ${artifact.path} preserves non-generated unit(s): ${artifact.preservedCustom.slice(0, 3).join("; ")}${artifact.preservedCustom.length > 3 ? "\u2026" : ""}`
+      );
+    }
+  }
+  for (const artifact of result.skippedFiles) {
+    if (artifact.reason === "already-current" && artifact.preservedCustom && artifact.preservedCustom.length > 0) {
+      lines.push(
+        ` [warn] ${artifact.path} preserves non-generated unit(s): ${artifact.preservedCustom.slice(0, 3).join("; ")}${artifact.preservedCustom.length > 3 ? "\u2026" : ""}`
+      );
+    }
+  }
+  return lines;
+}
 async function runCLI(argv, runtime = {}) {
   const log = runtime.log ?? console.log;
   const errorLog = runtime.errorLog ?? console.error;
@@ -12128,18 +12998,44 @@ async function runCLI(argv, runtime = {}) {
     for (const file of result.files) {
       log(` - ${file.path}`);
     }
+    if (result.writtenDetails?.length || result.skippedFiles?.length) {
+      for (const artifact of result.writtenDetails ?? []) {
+        if (artifact.kind === "database" || artifact.kind === "registry") {
+          log(formatWrittenArtifactLine(artifact));
+        }
+      }
+      for (const artifact of result.skippedFiles ?? []) {
+        if (artifact.kind === "database" || artifact.kind === "registry") {
+          log(formatSkippedArtifactLine(artifact));
+        }
+      }
+      for (const line of formatCustomPreserveWarnings(result)) {
+        log(line);
+      }
+    }
     return;
   }
   log(`Generated ${result.writtenFiles.length} files from ${result.configPath}`);
   for (const line of formatGeneratorModeLines(result)) {
     log(line);
   }
+  const detailByPath = new Map(
+    (result.writtenDetails ?? []).map((detail) => [detail.path, detail])
+  );
   for (const filePath of result.writtenFiles) {
-    log(` - ${filePath}`);
+    const detail = detailByPath.get(filePath);
+    if (detail && (detail.reason === "merged" || detail.reason === "overwritten")) {
+      log(formatWrittenArtifactLine(detail));
+    } else {
+      log(` - ${filePath}`);
+    }
   }
   for (const artifact of result.skippedFiles) {
     log(formatSkippedArtifactLine(artifact));
   }
+  for (const line of formatCustomPreserveWarnings(result)) {
+    log(line);
+  }
 }
 
 export { logCliError, parseCommand, runCLI, usage };