@ncukondo/reference-manager 0.19.0 → 0.20.0

package/dist/chunks/{index-Di6yhlFH.js → index-Cno7_aWr.js}

@@ -6,8 +6,8 @@ import * as os from "node:os";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 import path__default, { extname, join, basename, dirname } from "node:path";
+import { g as getExtension, i as isValidFulltextFiles, a as isReservedRole, R as RESERVED_ROLES, F as FULLTEXT_ROLE, b as formatToExtension, c as findFulltextFiles, d as findFulltextFile, e as extensionToFormat, B as BUILTIN_STYLES, h as getFulltextAttachmentTypes, s as startServerWithFileWatcher } from "./index-DrZawbND.js";
 import fs__default, { stat, rename, copyFile, readFile, unlink, readdir, mkdir, rm } from "node:fs/promises";
-import { g as getExtension, i as isValidFulltextFiles, a as isReservedRole, F as FULLTEXT_ROLE, b as formatToExtension, c as findFulltextFiles, d as findFulltextFile, e as extensionToFormat, B as BUILTIN_STYLES, h as getFulltextAttachmentTypes, s as startServerWithFileWatcher } from "./index-B4gr0P83.js";
 import { o as openWithSystemApp, l as loadConfig, e as getDefaultCurrentDirConfigFilename, h as getDefaultUserConfigPath } from "./loader-BtW20O32.js";
 import { spawn, spawnSync } from "node:child_process";
 import process$1, { stdin, stdout } from "node:process";
@@ -20,7 +20,7 @@ import "@citation-js/plugin-csl";
 import { ZodOptional as ZodOptional$2, z } from "zod";
 import { serve } from "@hono/node-server";
 const name = "@ncukondo/reference-manager";
-const version$1 = "0.19.0";
+const version$1 = "0.20.0";
 const description$1 = "A local reference management tool using CSL-JSON as the single source of truth";
 const packageJson = {
   name,
@@ -414,6 +414,44 @@ function getExitCode(result) {
   }
   return 0;
 }
+function slugifyLabel(label) {
+  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function generateFilename(role, ext, label) {
+  if (label) {
+    const slug = slugifyLabel(label);
+    return `${role}-${slug}.${ext}`;
+  }
+  return `${role}.${ext}`;
+}
+function parseFilename(filename) {
+  if (!filename) {
+    return null;
+  }
+  const ext = path__default.extname(filename);
+  const extWithoutDot = ext.startsWith(".") ? ext.slice(1) : ext;
+  const basename2 = ext ? filename.slice(0, -ext.length) : filename;
+  const firstHyphenIndex = basename2.indexOf("-");
+  if (firstHyphenIndex === -1) {
+    return {
+      role: basename2,
+      ext: extWithoutDot
+    };
+  }
+  const role = basename2.slice(0, firstHyphenIndex);
+  const label = basename2.slice(firstHyphenIndex + 1);
+  if (label) {
+    return {
+      role,
+      ext: extWithoutDot,
+      label
+    };
+  }
+  return {
+    role,
+    ext: extWithoutDot
+  };
+}
 function normalizePathForOutput(p) {
   return p.replace(/\\/g, "/");
 }
@@ -464,44 +502,6 @@ async function deleteDirectoryIfEmpty(dirPath) {
     }
   }
 }
-function slugifyLabel(label) {
-  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-}
-function generateFilename(role, ext, label) {
-  if (label) {
-    const slug = slugifyLabel(label);
-    return `${role}-${slug}.${ext}`;
-  }
-  return `${role}.${ext}`;
-}
-function parseFilename(filename) {
-  if (!filename) {
-    return null;
-  }
-  const ext = path__default.extname(filename);
-  const extWithoutDot = ext.startsWith(".") ? ext.slice(1) : ext;
-  const basename2 = ext ? filename.slice(0, -ext.length) : filename;
-  const firstHyphenIndex = basename2.indexOf("-");
-  if (firstHyphenIndex === -1) {
-    return {
-      role: basename2,
-      ext: extWithoutDot
-    };
-  }
-  const role = basename2.slice(0, firstHyphenIndex);
-  const label = basename2.slice(firstHyphenIndex + 1);
-  if (label) {
-    return {
-      role,
-      ext: extWithoutDot,
-      label
-    };
-  }
-  return {
-    role,
-    ext: extWithoutDot
-  };
-}
 async function checkSourceFile(filePath) {
   try {
     await stat(filePath);
@@ -794,6 +794,19 @@ async function detachAttachment(library, options) {
 function errorResult(error) {
   return { success: false, newFiles: [], missingFiles: [], applied: false, error };
 }
+function suggestRoleFromContext(filename, existingFiles) {
+  const ext = filename.toLowerCase();
+  const dataExtensions = [".xlsx", ".csv", ".tsv", ".zip"];
+  if (dataExtensions.some((de) => ext.endsWith(de)) || ext.endsWith(".tar.gz")) {
+    return "supplement";
+  }
+  const isDocumentLike = ext.endsWith(".pdf") || ext.endsWith(".md");
+  if (isDocumentLike) {
+    const hasFulltext = existingFiles.some((f) => f.role === "fulltext");
+    return hasFulltext ? "supplement" : "fulltext";
+  }
+  return null;
+}
 function inferFromFilename(filename) {
   const parsed = parseFilename(filename);
   if (!parsed) {
@@ -836,14 +849,17 @@ function findNewFiles(diskFiles, metadataFilenames) {
 function findMissingFiles(metadataFiles, diskFilenames) {
   return metadataFiles.filter((f) => !diskFilenames.has(f.filename)).map((f) => f.filename);
 }
-function buildUpdatedFiles(metadataFiles, newFiles, missingFiles, shouldApplyNew, shouldApplyFix) {
+function buildUpdatedFiles(metadataFiles, newFiles, missingFiles, shouldApplyNew, shouldApplyFix, roleOverrides) {
   let updatedFiles = [...metadataFiles];
   if (shouldApplyNew) {
     for (const newFile of newFiles) {
+      const override = roleOverrides?.[newFile.filename];
+      const role = override?.role ?? newFile.role;
+      const label = override ? override.label : newFile.label;
       const attachmentFile = {
         filename: newFile.filename,
-        role: newFile.role,
-        ...newFile.label && { label: newFile.label }
+        role,
+        ...label && { label }
       };
       updatedFiles.push(attachmentFile);
     }
@@ -854,6 +870,36 @@ function buildUpdatedFiles(metadataFiles, newFiles, missingFiles, shouldApplyNew
   }
   return updatedFiles;
 }
+async function applyRenames(dirPath, renames) {
+  const applied = {};
+  for (const [oldName, newName] of Object.entries(renames)) {
+    const oldPath = join(dirPath, oldName);
+    const newPath = join(dirPath, newName);
+    try {
+      await stat(newPath);
+      process.stderr.write(
+        `Warning: Cannot rename ${oldName} → ${newName}: target already exists
+`
+      );
+    } catch {
+      try {
+        await rename(oldPath, newPath);
+        applied[oldName] = newName;
+      } catch {
+      }
+    }
+  }
+  return applied;
+}
+function applyRenamesInMetadata(files, appliedRenames) {
+  return files.map((f) => {
+    const newName = appliedRenames[f.filename];
+    if (newName) {
+      return { ...f, filename: newName };
+    }
+    return f;
+  });
+}
 async function updateAttachmentMetadata(library, item, attachments, updatedFiles) {
   await library.update(item.id, {
     custom: {
@@ -866,7 +912,15 @@ async function updateAttachmentMetadata(library, item, attachments, updatedFiles
   });
 }
 async function syncAttachments(library, options) {
-  const { identifier, yes = false, fix = false, idType = "id", attachmentsDirectory } = options;
+  const {
+    identifier,
+    yes = false,
+    fix = false,
+    idType = "id",
+    attachmentsDirectory,
+    roleOverrides,
+    renames
+  } = options;
   const item = await library.find(identifier, { idType });
   if (!item) {
     return errorResult(`Reference '${identifier}' not found`);
@@ -889,13 +943,20 @@ async function syncAttachments(library, options) {
   const shouldApplyFix = fix && missingFiles.length > 0;
   const shouldApply = shouldApplyNew || shouldApplyFix;
   if (shouldApply) {
-    const updatedFiles = buildUpdatedFiles(
+    let updatedFiles = buildUpdatedFiles(
       metadataFiles,
       newFiles,
       missingFiles,
       shouldApplyNew,
-      shouldApplyFix
+      shouldApplyFix,
+      roleOverrides
     );
+    if (shouldApplyNew && renames && Object.keys(renames).length > 0) {
+      const appliedRenames = await applyRenames(dirPath, renames);
+      if (Object.keys(appliedRenames).length > 0) {
+        updatedFiles = applyRenamesInMetadata(updatedFiles, appliedRenames);
+      }
+    }
     await updateAttachmentMetadata(library, item, attachments, updatedFiles);
     await library.save();
   }
@@ -1032,15 +1093,15 @@ class OperationsLibrary {
   }
   // High-level operations
   async search(options) {
-    const { searchReferences } = await import("./index-B4gr0P83.js").then((n) => n.n);
+    const { searchReferences } = await import("./index-DrZawbND.js").then((n) => n.n);
     return searchReferences(this.library, options);
   }
   async list(options) {
-    const { listReferences } = await import("./index-B4gr0P83.js").then((n) => n.m);
+    const { listReferences } = await import("./index-DrZawbND.js").then((n) => n.m);
     return listReferences(this.library, options ?? {});
   }
   async cite(options) {
-    const { citeReferences } = await import("./index-B4gr0P83.js").then((n) => n.l);
+    const { citeReferences } = await import("./index-DrZawbND.js").then((n) => n.l);
     const defaultStyle = options.defaultStyle ?? this.citationConfig?.defaultStyle;
     const cslDirectory = options.cslDirectory ?? this.citationConfig?.cslDirectory;
     const mergedOptions = {
@@ -1051,32 +1112,32 @@ class OperationsLibrary {
     return citeReferences(this.library, mergedOptions);
   }
   async import(inputs, options) {
-    const { addReferences } = await import("./index-B4gr0P83.js").then((n) => n.k);
+    const { addReferences } = await import("./index-DrZawbND.js").then((n) => n.k);
     return addReferences(inputs, this.library, options ?? {});
   }
   // Attachment operations
   async attachAdd(options) {
-    const { addAttachment: addAttachment2 } = await import("./index-BJf01yMW.js");
+    const { addAttachment: addAttachment2 } = await import("./index-BR5tlrNU.js");
     return addAttachment2(this.library, options);
   }
   async attachList(options) {
-    const { listAttachments: listAttachments2 } = await import("./index-BJf01yMW.js");
+    const { listAttachments: listAttachments2 } = await import("./index-BR5tlrNU.js");
     return listAttachments2(this.library, options);
   }
   async attachGet(options) {
-    const { getAttachment: getAttachment2 } = await import("./index-BJf01yMW.js");
+    const { getAttachment: getAttachment2 } = await import("./index-BR5tlrNU.js");
     return getAttachment2(this.library, options);
   }
   async attachDetach(options) {
-    const { detachAttachment: detachAttachment2 } = await import("./index-BJf01yMW.js");
+    const { detachAttachment: detachAttachment2 } = await import("./index-BR5tlrNU.js");
     return detachAttachment2(this.library, options);
   }
   async attachSync(options) {
-    const { syncAttachments: syncAttachments2 } = await import("./index-BJf01yMW.js");
+    const { syncAttachments: syncAttachments2 } = await import("./index-BR5tlrNU.js");
     return syncAttachments2(this.library, options);
   }
   async attachOpen(options) {
-    const { openAttachment: openAttachment2 } = await import("./index-BJf01yMW.js");
+    const { openAttachment: openAttachment2 } = await import("./index-BR5tlrNU.js");
     return openAttachment2(this.library, options);
   }
 }
@@ -1536,6 +1597,62 @@ async function readConfirmation(prompt) {
     });
   });
 }
+async function readChoice(prompt, choices, defaultIndex) {
+  if (choices.length === 0) {
+    throw new Error("readChoice requires at least one choice");
+  }
+  const effectiveDefault = defaultIndex !== void 0 && defaultIndex >= 0 && defaultIndex < choices.length ? defaultIndex : 0;
+  const getDefault = () => {
+    const choice = choices[effectiveDefault];
+    if (!choice) throw new Error("Invalid default index");
+    return choice.value;
+  };
+  const parseAnswer = (answer) => {
+    const trimmed = answer.trim();
+    if (trimmed === "") return getDefault();
+    const num = Number.parseInt(trimmed, 10);
+    if (Number.isNaN(num) || num < 1 || num > choices.length) return getDefault();
+    const selected = choices[num - 1];
+    return selected ? selected.value : getDefault();
+  };
+  if (!isTTY()) {
+    return getDefault();
+  }
+  if (process.stdin.isTTY && process.stdin.isRaw) {
+    process.stdin.setRawMode(false);
+  }
+  process.stdin.resume();
+  process.stdin.ref();
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  process.stderr.write(`${prompt}
+`);
+  for (let i = 0; i < choices.length; i++) {
+    const choice = choices[i];
+    if (!choice) continue;
+    const marker = i === effectiveDefault ? " (default)" : "";
+    process.stderr.write(`  ${i + 1}) ${choice.label}${marker}
+`);
+  }
+  return new Promise((resolve2) => {
+    let resolved = false;
+    rl.question("Enter number: ", (answer) => {
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        resolve2(parseAnswer(answer));
+      }
+    });
+    rl.on("close", () => {
+      if (!resolved) {
+        resolved = true;
+        resolve2(getDefault());
+      }
+    });
+  });
+}
 async function readStdinContent() {
   const chunks = [];
   for await (const chunk of stdin) {
@@ -1658,7 +1775,9 @@ async function executeAttachSync(options, context) {
     attachmentsDirectory: options.attachmentsDirectory,
     ...options.yes !== void 0 && { yes: options.yes },
     ...options.fix !== void 0 && { fix: options.fix },
-    ...options.idType !== void 0 && { idType: options.idType }
+    ...options.idType !== void 0 && { idType: options.idType },
+    ...options.roleOverrides !== void 0 && { roleOverrides: options.roleOverrides },
+    ...options.renames !== void 0 && { renames: options.renames }
   };
   return syncAttachments(context.library, operationOptions);
 }
@@ -1755,6 +1874,73 @@ function formatMissingFilesSection(result, lines) {
   }
   lines.push("");
 }
+function buildRoleOverridesFromSuggestions(newFiles) {
+  const overrides = {};
+  for (const file of newFiles) {
+    if (file.role !== "other") continue;
+    const suggested = suggestRoleFromContext(file.filename, newFiles);
+    if (suggested) {
+      overrides[file.filename] = { role: suggested };
+    }
+  }
+  return overrides;
+}
+function generateRenameMap(newFiles, overrides) {
+  const renames = {};
+  for (const file of newFiles) {
+    const override = overrides[file.filename];
+    if (!override) continue;
+    const ext = path__default.extname(file.filename);
+    const extWithoutDot = ext.startsWith(".") ? ext.slice(1) : ext;
+    const baseName = ext ? file.filename.slice(0, -ext.length) : file.filename;
+    const canonical = generateFilename(override.role, extWithoutDot, override.label);
+    if (canonical !== file.filename) {
+      const newName = override.label ? canonical : `${override.role}-${baseName}${ext}`;
+      renames[file.filename] = newName;
+    }
+  }
+  return renames;
+}
+function formatSuggestedFileEntry(file, suggestions, renames, lines) {
+  lines.push(`    ${file.filename}`);
+  const suggestion = suggestions[file.filename];
+  if (suggestion) {
+    lines.push(`      role: ${suggestion.role} (suggested, inferred: ${file.role})`);
+  } else {
+    const labelPart = file.label ? `, label: "${file.label}"` : "";
+    lines.push(`      role: ${file.role}${labelPart}`);
+  }
+  const rename2 = renames[file.filename];
+  if (rename2) {
+    lines.push(`      rename: ${rename2}`);
+  }
+}
+function formatSyncPreviewWithSuggestions(result, suggestions, renames, identifier) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  const hasNewFiles = result.newFiles.length > 0;
+  const hasMissingFiles = result.missingFiles.length > 0;
+  const hasRenames = Object.keys(renames).length > 0;
+  if (!hasNewFiles && !hasMissingFiles) {
+    return "Already in sync.";
+  }
+  const lines = [];
+  lines.push(`Sync preview for ${identifier}:`);
+  if (hasNewFiles) {
+    lines.push("  New files:");
+    for (const file of result.newFiles) {
+      formatSuggestedFileEntry(file, suggestions, renames, lines);
+    }
+    lines.push("");
+  }
+  formatMissingFilesSection(result, lines);
+  lines.push(`To apply: ref attach sync ${identifier} --yes`);
+  if (hasRenames) {
+    lines.push(`To apply without renaming: ref attach sync ${identifier} --yes --no-rename`);
+  }
+  return lines.join("\n").trimEnd();
+}
 function formatAttachSyncOutput(result) {
   if (!result.success) {
     return `Error: ${result.error}`;
@@ -1795,7 +1981,7 @@ function getAttachExitCode(result) {
 }
 async function executeInteractiveSelect$2(context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferencesOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferencesOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const identifiers = await withAlternateScreen2(
     () => selectReferencesOrExit(allReferences, { multiSelect: false }, config2.cli.tui)
@@ -1853,44 +2039,95 @@ async function waitForEnter() {
     });
   });
 }
-function displayInteractiveSyncResult(result, identifier) {
-  if (result.newFiles.length === 0) {
-    process.stderr.write("No new files detected.\n");
-    return;
+async function promptForRenames(renameMap) {
+  const accepted = {};
+  for (const [oldName, newName] of Object.entries(renameMap)) {
+    const shouldRename = await readConfirmation(`Rename ${oldName} → ${newName}?`);
+    if (shouldRename) {
+      accepted[oldName] = newName;
+    }
   }
-  process.stderr.write("Scanning directory...\n\n");
+  return accepted;
+}
+function showFilePreview(previewFiles, acceptedRenames) {
+  process.stderr.write("\nScanning directory...\n\n");
   process.stderr.write(
-    `Found ${result.newFiles.length} new file${result.newFiles.length > 1 ? "s" : ""}:
+    `Found ${previewFiles.length} new file${previewFiles.length > 1 ? "s" : ""}:
 `
   );
-  for (const file of result.newFiles) {
+  for (const file of previewFiles) {
     const labelPart = file.label ? `, label: "${file.label}"` : "";
-    process.stderr.write(`  ✓ ${file.filename} → role: ${file.role}${labelPart}
-`);
+    const renamePart = acceptedRenames[file.filename] ? ` (rename → ${acceptedRenames[file.filename]})` : "";
+    process.stderr.write(
+      `  ✓ ${file.filename} → role: ${file.role}${labelPart}${renamePart}
+`
+    );
   }
-  process.stderr.write(`
-Updated metadata for ${identifier}.
-`);
 }
-async function runInteractiveMode(identifier, dirPath, attachmentsDirectory, idType, context) {
-  displayNamingConvention(identifier, dirPath);
-  await waitForEnter();
-  const syncResult = await executeAttachSync(
+function buildPreviewFiles(newFiles, roleOverrides) {
+  return newFiles.map((file) => {
+    const override = roleOverrides[file.filename];
+    if (override) {
+      return { ...file, role: override.role, ...override.label && { label: override.label } };
+    }
+    return file;
+  });
+}
+async function syncNewFilesWithRolePrompt(identifier, attachmentsDirectory, idType, context) {
+  const dryRunResult = await executeAttachSync(
     {
       identifier,
       attachmentsDirectory,
-      yes: true,
       ...idType && { idType }
     },
     context
   );
-  if (syncResult.success) {
-    displayInteractiveSyncResult(syncResult, identifier);
+  if (!dryRunResult.success) {
+    process.stderr.write(`Sync error: ${dryRunResult.error}
+`);
+    return;
+  }
+  if (dryRunResult.newFiles.length === 0) {
+    process.stderr.write("No new files detected.\n");
+    return;
+  }
+  const roleOverrides = await promptForUnknownRoles(dryRunResult.newFiles);
+  const renameMap = generateRenameMap(dryRunResult.newFiles, roleOverrides);
+  const acceptedRenames = await promptForRenames(renameMap);
+  const previewFiles = buildPreviewFiles(dryRunResult.newFiles, roleOverrides);
+  showFilePreview(previewFiles, acceptedRenames);
+  const shouldApply = await readConfirmation("\nAdd new files to metadata?");
+  if (!shouldApply) {
+    process.stderr.write("No changes applied.\n");
+    return;
+  }
+  const hasOverrides = Object.keys(roleOverrides).length > 0;
+  const hasRenames = Object.keys(acceptedRenames).length > 0;
+  const applyResult = await executeAttachSync(
+    {
+      identifier,
+      attachmentsDirectory,
+      yes: true,
+      ...idType && { idType },
+      ...hasOverrides && { roleOverrides },
+      ...hasRenames && { renames: acceptedRenames }
+    },
+    context
+  );
+  if (applyResult.success) {
+    process.stderr.write(`
+Updated metadata for ${identifier}.
+`);
   } else {
-    process.stderr.write(`Sync error: ${syncResult.error}
+    process.stderr.write(`Sync error: ${applyResult.error}
 `);
   }
 }
+async function runInteractiveMode(identifier, dirPath, attachmentsDirectory, idType, context) {
+  displayNamingConvention(identifier, dirPath);
+  await waitForEnter();
+  await syncNewFilesWithRolePrompt(identifier, attachmentsDirectory, idType, context);
+}
 function buildOpenOptions(identifier, filenameArg, options, attachmentsDirectory) {
   return {
     identifier,
@@ -2049,6 +2286,30 @@ async function handleAttachDetachAction(identifierArg, filenameArg, options, glo
     setExitCode(ExitCode.INTERNAL_ERROR);
   }
 }
+async function promptForUnknownRoles(newFiles) {
+  const overrides = {};
+  const unknownFiles = newFiles.filter((f) => f.role === "other");
+  if (unknownFiles.length === 0) return overrides;
+  process.stderr.write("\nSome files could not be classified by filename:\n");
+  const roleChoices = [
+    ...RESERVED_ROLES.map((r) => ({ label: r, value: r })),
+    { label: "other (keep as-is)", value: "other" }
+  ];
+  for (const file of unknownFiles) {
+    const suggested = suggestRoleFromContext(file.filename, newFiles);
+    const defaultIndex = suggested ? roleChoices.findIndex((c) => c.value === suggested) : void 0;
+    const selectedRole = await readChoice(
+      `
+Role for "${file.filename}"?`,
+      roleChoices,
+      defaultIndex !== void 0 && defaultIndex >= 0 ? defaultIndex : void 0
+    );
+    if (selectedRole !== "other") {
+      overrides[file.filename] = { role: selectedRole };
+    }
+  }
+  return overrides;
+}
 async function runInteractiveSyncMode(identifier, attachmentsDirectory, idType, context) {
   const dryRunOptions = {
     identifier,
@@ -2063,7 +2324,12 @@ async function runInteractiveSyncMode(identifier, attachmentsDirectory, idType,
 `);
     return;
   }
-  process.stderr.write(`${formatSyncPreview(dryRunResult)}
+  const roleOverrides = await promptForUnknownRoles(dryRunResult.newFiles);
+  const renameMap = generateRenameMap(dryRunResult.newFiles, roleOverrides);
+  const acceptedRenames = await promptForRenames(renameMap);
+  const previewFiles = buildPreviewFiles(dryRunResult.newFiles, roleOverrides);
+  const previewResult = { ...dryRunResult, newFiles: previewFiles };
+  process.stderr.write(`${formatSyncPreview(previewResult)}
 `);
   const shouldApplyNew = hasNewFiles && await readConfirmation("Add new files to metadata?");
   const shouldApplyFix = hasMissingFiles && await readConfirmation("Remove missing files from metadata?");
@@ -2071,16 +2337,70 @@ async function runInteractiveSyncMode(identifier, attachmentsDirectory, idType,
     process.stderr.write("No changes applied.\n");
     return;
   }
+  const hasRenames = Object.keys(acceptedRenames).length > 0;
   const applyOptions = {
     identifier,
     attachmentsDirectory,
     ...shouldApplyNew && { yes: true },
     ...shouldApplyFix && { fix: true },
+    ...idType && { idType },
+    ...shouldApplyNew && Object.keys(roleOverrides).length > 0 && { roleOverrides },
+    ...shouldApplyNew && hasRenames && { renames: acceptedRenames }
+  };
+  const result = await executeAttachSync(applyOptions, context);
+  process.stderr.write(`${formatAttachSyncOutput(result)}
+`);
+}
+async function handleSyncApplyWithSuggestions(identifier, attachmentsDirectory, idType, context, fix, noRename) {
+  const dryRunOptions = {
+    identifier,
+    attachmentsDirectory,
     ...idType && { idType }
   };
+  const dryRunResult = await executeAttachSync(dryRunOptions, context);
+  if (!dryRunResult.success) {
+    process.stderr.write(`${formatAttachSyncOutput(dryRunResult)}
+`);
+    setExitCode(getAttachExitCode(dryRunResult));
+    return;
+  }
+  const suggestions = buildRoleOverridesFromSuggestions(dryRunResult.newFiles);
+  const renames = noRename ? {} : generateRenameMap(dryRunResult.newFiles, suggestions);
+  const hasRenames = Object.keys(renames).length > 0;
+  const applyOptions = {
+    identifier,
+    attachmentsDirectory,
+    yes: true,
+    ...fix && { fix: true },
+    ...idType && { idType },
+    ...Object.keys(suggestions).length > 0 && { roleOverrides: suggestions },
+    ...hasRenames && { renames }
+  };
   const result = await executeAttachSync(applyOptions, context);
   process.stderr.write(`${formatAttachSyncOutput(result)}
 `);
+  setExitCode(getAttachExitCode(result));
+}
+async function handleSyncDryRunPreview(identifier, attachmentsDirectory, idType, context) {
+  const dryRunOptions = {
+    identifier,
+    attachmentsDirectory,
+    ...idType && { idType }
+  };
+  const dryRunResult = await executeAttachSync(dryRunOptions, context);
+  if (!dryRunResult.success) {
+    process.stderr.write(`${formatAttachSyncOutput(dryRunResult)}
+`);
+    setExitCode(getAttachExitCode(dryRunResult));
+    return;
+  }
+  const suggestions = buildRoleOverridesFromSuggestions(dryRunResult.newFiles);
+  const renames = generateRenameMap(dryRunResult.newFiles, suggestions);
+  process.stderr.write(
+    `${formatSyncPreviewWithSuggestions(dryRunResult, suggestions, renames, identifier)}
+`
+  );
+  setExitCode(getAttachExitCode(dryRunResult));
 }
 async function handleAttachSyncAction(identifierArg, options, globalOpts) {
   try {
@@ -2089,17 +2409,31 @@ async function handleAttachSyncAction(identifierArg, options, globalOpts) {
     const identifier = await resolveIdentifier(identifierArg, context, config2);
     const attachmentsDirectory = config2.attachments.directory;
     const idType = options.uuid ? "uuid" : void 0;
-    const shouldUseInteractive = isTTY() && !options.yes && !options.fix;
-    if (shouldUseInteractive) {
+    if (isTTY() && !options.yes && !options.fix) {
       await runInteractiveSyncMode(identifier, attachmentsDirectory, idType, context);
       setExitCode(ExitCode.SUCCESS);
       return;
     }
+    const noRename = options.noRename || options.rename === false;
+    if (options.yes) {
+      await handleSyncApplyWithSuggestions(
+        identifier,
+        attachmentsDirectory,
+        idType,
+        context,
+        options.fix,
+        noRename
+      );
+      return;
+    }
+    if (!options.fix) {
+      await handleSyncDryRunPreview(identifier, attachmentsDirectory, idType, context);
+      return;
+    }
     const syncOptions = {
       identifier,
       attachmentsDirectory,
-      ...options.yes && { yes: true },
-      ...options.fix && { fix: true },
+      fix: true,
       ...idType && { idType }
     };
     const result = await executeAttachSync(syncOptions, context);
@@ -2114,6 +2448,7 @@ async function handleAttachSyncAction(identifierArg, options, globalOpts) {
 }
 const attach = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
+  buildRoleOverridesFromSuggestions,
   executeAttachAdd,
   executeAttachDetach,
   executeAttachGet,
@@ -2125,6 +2460,8 @@ const attach = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProper
   formatAttachListOutput,
   formatAttachOpenOutput,
   formatAttachSyncOutput,
+  formatSyncPreviewWithSuggestions,
+  generateRenameMap,
   getAttachExitCode,
   handleAttachAddAction,
   handleAttachDetachAction,
@@ -2132,7 +2469,8 @@ const attach = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProper
   handleAttachListAction,
   handleAttachOpenAction,
   handleAttachSyncAction,
-  runInteractiveMode
+  runInteractiveMode,
+  syncNewFilesWithRolePrompt
 }, Symbol.toStringTag, { value: "Module" }));
 async function validateOptions$2(options) {
   if (options.output && !["text", "html", "rtf"].includes(options.output)) {
@@ -2191,8 +2529,8 @@ function getCiteExitCode(result) {
 }
 async function executeInteractiveCite(options, context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { runCiteFlow } = await import("./index-C49EfSAl.js");
-  const { buildStyleChoices, listCustomStyles } = await import("./style-select-UWYScO8e.js");
+  const { runCiteFlow } = await import("./index-D--7n1SB.js");
+  const { buildStyleChoices, listCustomStyles } = await import("./style-select-DxcSWBSF.js");
   const { search } = await import("./file-watcher-CrsNHUpz.js").then((n) => n.z);
   const { tokenize } = await import("./file-watcher-CrsNHUpz.js").then((n) => n.y);
   const { checkTTY } = await import("./tty-BMyaEOhX.js");
@@ -6749,7 +7087,7 @@ function formatEditOutput(result) {
 }
 async function executeInteractiveEdit(options, context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferencesOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferencesOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const identifiers = await withAlternateScreen2(
     () => selectReferencesOrExit(allReferences, { multiSelect: true }, config2.cli.tui)
@@ -10403,7 +10741,7 @@ function getFulltextExitCode(result) {
 }
 async function executeInteractiveSelect$1(context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferencesOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferencesOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const identifiers = await withAlternateScreen2(
     () => selectReferencesOrExit(allReferences, { multiSelect: false }, config2.cli.tui)
@@ -31436,7 +31774,7 @@ async function mcpStart(options) {
 async function executeRemove(options, context) {
   const { identifier, idType = "id", fulltextDirectory, deleteFulltext = false } = options;
   if (context.mode === "local" && deleteFulltext && fulltextDirectory) {
-    const { removeReference } = await import("./index-B4gr0P83.js").then((n) => n.r);
+    const { removeReference } = await import("./index-DrZawbND.js").then((n) => n.r);
     return removeReference(context.library, {
       identifier,
       idType,
@@ -31491,7 +31829,7 @@ Continue?`;
 }
 async function executeInteractiveRemove(context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferenceItemsOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferenceItemsOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const selectedItems = await withAlternateScreen2(
     () => selectReferenceItemsOrExit(allReferences, { multiSelect: false }, config2.cli.tui)
@@ -31716,7 +32054,7 @@ async function executeInteractiveSearch(options, context, config2) {
   validateInteractiveOptions(options);
   const { checkTTY } = await import("./tty-BMyaEOhX.js");
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { runSearchFlow } = await import("./index-C49EfSAl.js");
+  const { runSearchFlow } = await import("./index-D--7n1SB.js");
   const { search } = await import("./file-watcher-CrsNHUpz.js").then((n) => n.z);
   const { tokenize } = await import("./file-watcher-CrsNHUpz.js").then((n) => n.y);
   checkTTY();
@@ -31735,7 +32073,7 @@ async function executeInteractiveSearch(options, context, config2) {
     })
   );
   if (result.selectedItems && !result.cancelled) {
-    const { isSideEffectAction } = await import("./action-menu-BoJkH1yr.js");
+    const { isSideEffectAction } = await import("./action-menu-Brg5Lmz7.js");
     if (isSideEffectAction(result.action)) {
       await executeSideEffectAction(result.action, result.selectedItems, context, config2);
       return { output: "", cancelled: false, action: result.action };
@@ -32138,7 +32476,7 @@ function formatUpdateOutput(result, identifier) {
 }
 async function executeInteractiveUpdate(context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferencesOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferencesOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const identifiers = await withAlternateScreen2(
     () => selectReferencesOrExit(allReferences, { multiSelect: false }, config2.cli.tui)
@@ -32433,7 +32771,7 @@ function getUrlExitCode(result) {
 }
 async function executeInteractiveSelect(context, config2) {
   const { withAlternateScreen: withAlternateScreen2 } = await Promise.resolve().then(() => alternateScreen);
-  const { selectReferencesOrExit } = await import("./reference-select-D4iGJ4kA.js");
+  const { selectReferencesOrExit } = await import("./reference-select-DrINWBuP.js");
   const allReferences = await context.library.getAll();
   const identifiers = await withAlternateScreen2(
     () => selectReferencesOrExit(allReferences, { multiSelect: false }, config2.cli.tui)
@@ -33116,7 +33454,7 @@ function registerAttachCommand(program) {
   attachCmd.command("detach").description("Detach file from a reference").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").argument("[filename]", "Specific file to detach").option("--role <role>", "Detach files by role").option("--all", "Detach all files of specified role").option("--remove-files", "Also delete files from disk").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filename, options) => {
     await handleAttachDetachAction(identifier, filename, options, program.opts());
   });
-  attachCmd.command("sync").description("Synchronize metadata with files on disk").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--yes", "Apply changes (add new files)").option("--fix", "Remove missing files from metadata").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+  attachCmd.command("sync").description("Synchronize metadata with files on disk").argument("[identifier]", "Citation key or UUID (interactive selection if omitted)").option("--yes", "Apply changes (add new files)").option("--fix", "Remove missing files from metadata").option("--no-rename", "Skip file renaming (keep original filenames)").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
     await handleAttachSyncAction(identifier, options, program.opts());
   });
 }
@@ -33170,4 +33508,4 @@ export {
   restoreStdinAfterInk as r,
   syncAttachments as s
 };
-//# sourceMappingURL=index-Di6yhlFH.js.map
+//# sourceMappingURL=index-Cno7_aWr.js.map