@im-nobsidian/core 0.19.1 → 0.21.0

package/dist/index.d.ts

@@ -603,8 +603,8 @@ interface PullResult {
      */
     readonly relinkPending?: true;
     /**
-     * dry-run 만 — 이번 pull 이 새로 찾을 DB(처음 훑는 볼트 · 새로 받을 페이지 안의 DB)의 행은 세지 않았다. 받아 봐야 그 DB 가
-     * 있는지 안다. 없으면 생략.
+     * dry-run 만 — 본문을 읽지 않은 새 페이지 안의 DB 행은 세지 않았다. 받아 봐야 그 DB 가 있는지 안다. 루트 아래 · 미리 보며
+     * 읽은 본문 안의 새 DB 는 센다. 없으면 생략.
      */
     readonly undiscoveredDatabases?: true;
     /**
@@ -2821,6 +2821,12 @@ declare class SyncOrchestrator {
      * 있든 없든 push 마다 부른다 — 바뀌지 않은 첨부는 파일 기록이 건너뛴다.
      */
     private pushVaultFiles;
+    /**
+     * 폴더 첨부를 노트의 페이지에 붙이거나 지울 때({@link NotePageWrites}) — 쓰기 전에 원격과 맞던 노트만 쓴 뒤의 원격을 본
+     * 것으로 적는다. 받지 않은 Notion 편집이 걸린 노트를 적으면 다음 pull 이 그 편집을 받지 않는다. 읽지 못하면 적지 않는다 —
+     * 다음 push 가 그 노트를 올리지 않고 pull 을 먼저 하라고 알릴 뿐이다.
+     */
+    private notePageWrites;
     /**
      * @param mergedByPull sync dry-run 만 — 앞선 pull dry-run 이 합칠 노트. 실제 sync 는 합친 뒤 원격을 본 것으로
      *   적어 push 가 올린다 — dry-run 은 받지 않아 원격이 바뀐 그대로라, 원격을 보고 거절하지 않는다.
@@ -3105,6 +3111,16 @@ declare class ImageHandler {
     private readonly downloadTimeoutMs;
     constructor(vaultFs: VaultFS, attachmentFolder?: string, notionClient?: NotionClient | undefined, customFetch?: typeof globalThis.fetch, options?: MediaOptions, stateDb?: IStateDB | undefined);
     private get fetchFn();
+    /** {@link preview} 안에서 도는 중인 렌더 수 — 0 보다 크면 받은 미디어를 볼트에 쓰지 않고 상태 DB 에 적지 않는다. */
+    private previewDepth;
+    /**
+     * 받기를 미리 본다(dry-run) — 미디어를 실제 pull 처럼 받아 이름(내용 해시)과 임베드를 정하되 볼트에 쓰지 않고 상태 DB 에
+     * 적지 않는다. 받지 않고 렌더하면 미디어가 원격 주소로 남아, 받은 글을 볼트의 노트와 견줄 수 없다.
+     */
+    preview<T>(run: () => Promise<T>): Promise<T>;
+    private get previewing();
+    /** 받은 파일을 볼트에 쓴다 — 미리 보기에서는 쓰지 않는다({@link preview}). */
+    private writeDownload;
     /** 상한 로직은 첨부 경로와 공유한다 — 한쪽만 빠뜨리지 않도록(utils/download-fetch). */
     private fetchForDownload;
     downloadImage(url: string, pageTitle: string): Promise<ImageDownloadResult>;
@@ -3320,6 +3336,16 @@ interface FileHandlerOptions {
      */
     readonly deleteSync?: boolean;
 }
+/**
+ * 노트의 페이지에 폴더 첨부 블록을 붙이거나 지울 때(ADR-056) — 그 쓰기로 노트 페이지의 수정 시각 · 본문이 바뀐다. 알리지 않으면
+ * 다음 push 가 그 노트를 «Notion 에서도 바뀐 페이지» 로 보고 올리지 않는다.
+ */
+interface NotePageWrites {
+    /** 쓰기 전 — 그 노트가 지금 원격과 맞는지 본다. */
+    begin(pageId: string): Promise<void>;
+    /** 쓴 뒤 — 맞던 노트는 지금 원격을 본 것으로 적는다. 맞지 않던 노트(받지 않은 Notion 편집)는 그대로 둔다. */
+    end(pageId: string): Promise<void>;
+}
 /** 노트 없는 폴더의 Notion 페이지를 마련하는 쪽 — push 의 폴더 배치(`FolderPlacement`). */
 interface FolderPageProvider {
     /** 폴더의 페이지를 마련한다. 이미 있으면 그대로 둔다. 마련할 수 없으면 까닭과 함께 던진다. */
@@ -3366,12 +3392,28 @@ declare class FileHandler {
      * @returns 업로드 결과. 변경 없음(스킵)이거나 실패했으면 null.
      */
     private pushSingleFile;
-    /** 올린 뒤 바뀌지 않았나 — 크기가 같으면 읽지 않는다. */
+    /**
+     * 올리거나 받은 뒤 바뀌지 않았나 — 그때의 표(크기 · 수정 시각, {@link fileStampOf})와 같으면 읽지 않는다. 크기가 다르면 바뀌었다.
+     * 크기만 같으면 내용으로 견주고, 같으면 지금 표를 적어 다음에는 읽지 않는다. 예전에는 크기가 같으면 바뀌지 않았다고 봐, 같은
+     * 크기로 고친 파일을 올리지 않았다.
+     */
     private isUnchanged;
     /** pull 이 받은 것을 두는 폴더 안인가. */
     private inAttachmentsFolder;
-    /** 폴더 첨부를 둘 Notion 페이지 — 폴더 노트 없는 폴더의 페이지(폴더 레코드)만. 맨 위는 루트 기록이 있을 때만. */
+    /**
+     * 폴더 첨부를 둘 Notion 페이지 — 그 폴더의 Notion 자리({@link folderContainer} 와 같은 차례). 폴더 노트(`X/X.md`)나 노트
+     * 이름의 폴더(`X.md` 옆 `X/`)면 그 노트의 페이지 끝(ADR-056), 아니면 push 가 만든 폴더 페이지. 맨 위는 루트 기록이 있을 때만.
+     * 행 · DB 폴더는 둘 곳이 없다 — 행의 본문은 행의 것이다.
+     */
     private folderPageOf;
+    /** 이 폴더를 품은 노트의 페이지 — 폴더 노트 · 노트 이름의 폴더. 없거나 행이면 null. */
+    private notePageOf;
+    private folderRecordPageOf;
+    /**
+     * 이 기록이 그 폴더의 폴더 첨부인가. 노트의 페이지에는 그 노트가 임베드해 올린 파일도 같은 페이지로 적혀 있다 — 폴더
+     * 첨부로 적어 둔 것({@link folderFileIdsOf})만이다.
+     */
+    private isFolderFileEntry;
     /**
      * 업로드 후보 목록 — 도구 내부 산출물(`.base`/`.notion.json`)은 아예 빼고, Notion 이 받지 않는
      * 형식은 따로 모은다.
@@ -3390,12 +3432,14 @@ declare class FileHandler {
      * @param failed 올리지 못한 첨부를 담을 곳 — push 결과의 `failed` 를 넘기면 CLI · 플러그인이 처리하지 못한 것으로
      *   보인다. 예전엔 경고 로그로만 남아 push 가 「실패 0」 으로 끝났다.
      */
-    pushAllFiles(failed?: FailedOperation[], folders?: FolderPageProvider): Promise<FileUploadResult[]>;
+    pushAllFiles(failed?: FailedOperation[], folders?: FolderPageProvider, noteWrites?: NotePageWrites): Promise<FileUploadResult[]>;
     /**
      * 볼트에서 지운 폴더 첨부를 Notion 에서도 지운다(deleteSync) — 폴더 페이지에 적힌 파일 가운데 볼트에 없는 것의 블록과 기록.
      * 포함 · 제외 패턴으로 빠진 파일은 볼트에 있어 지우지 않는다.
      */
     private removeDeletedFolderFiles;
+    /** 노트의 페이지에 쓰는 동안을 알린다({@link NotePageWrites}) — 폴더 페이지는 노트가 없어 알릴 것이 없다. */
+    private writingNotePage;
     /** 폴더 첨부를 둘 페이지 — 노트 없는 폴더면 마련한다. 둘 곳이 없으면 그 파일들을 `stranded` 에 담고 null. */
     private provideFolderPage;
     /**
@@ -3434,11 +3478,23 @@ declare class FileHandler {
         caption?: string;
     }>, targetFolder: string): Promise<FileDownloadResult[]>;
     private uploadFile;
-    /** 이 페이지에서 같은 이름의 파일 블록 중 방금 붙인 것 말고를 지운다. */
+    /**
+     * 처음 보는 파일이 이 페이지에 적어 둔 같은 이름의 폴더 첨부를 옮긴 것인가 — 그 기록의 경로가 볼트에서 사라졌으면 옮겼다(폴더 ·
+     * 폴더 노트 · 노트의 이름 바꾸기). 기록 · 파일 id · 표를 새 경로로 옮긴다. `same` 이면 내용이 같아 올리지 않는다. 다르면 옮긴
+     * 기록을 옛 것으로 올려 옛 블록을 지운다. 예전에는 새 파일로 올려 노트 페이지에 같은 파일의 블록이 둘 남았다.
+     */
+    private movedHere;
+    /**
+     * 이 페이지에서 그 폴더 첨부의 블록 중 방금 붙인 것(`keep`) 말고를 지운다. 폴더 페이지는 같은 이름의 파일 블록 모두(id 를
+     * 적기 전에 올린 블록도). 노트의 페이지는 노트가 임베드한 같은 이름의 파일이 있을 수 있어, 적어 둔 Notion 파일 id 의 블록과
+     * 표시를 단 캡션({@link folderFileCaption})의 블록만 — 다른 볼트가 같은 파일을 먼저 고쳐 올린 블록은 id 를 모르지만 표시가 있다.
+     * 예전에는 id 로만 지워, 두 볼트가 따로 고쳐 올리면 블록이 둘 남았다.
+     */
     private removeOlderBlocks;
     /**
-     * 폴더 첨부의 파일 블록 — 캡션에 파일 이름을 적는다. 받는 쪽이 그 표시로 폴더 첨부를 알아본다({@link folderFilesOf}) —
-     * 자식 페이지가 없는 폴더 페이지는 PDF 하나만 붙인 노트와 모양이 같다.
+     * 폴더 첨부의 파일 블록 — 캡션에 표시를 단 파일 이름을 적는다({@link folderFileCaption}). 받는 쪽이 그 표시로 폴더 첨부를
+     * 알아본다 — 자식 페이지가 없는 폴더 페이지는 PDF 하나만 붙인 노트와 모양이 같고, 노트 페이지의 폴더 첨부는 그 노트의
+     * 임베드와 같은 블록이다.
      */
     private createFileBlock;
     private extractFilename;
@@ -3651,6 +3707,8 @@ interface PlannedRow {
     readonly resolution?: PlannedResolution;
     /** `create` 만 — 상태 기록에 없던 같은 자리의 행 노트를 다시 잇는다(P7). 새로 받는 것으로 세지 않는다. */
     readonly relink?: true;
+    /** 다시 잇되 글이 달라 충돌로 남긴다 — `relink` 와 같이. */
+    readonly relinkConflict?: Conflict;
 }
 /**
  * 로컬도 고친 노트를 실제 pull 이 어떻게 처리하나 — 충돌로 남김 · 합침(merge) · 받지 않음(원격이 그대로거나
@@ -4040,11 +4098,15 @@ declare class DatabaseSyncer {
      */
     private claimExistingRow;
     /**
-     * 상태 기록에 없던 행 노트를 이 행과 다시 잇는다(P7) — 페이지의 `relinkExistingNote` 와 같은 규칙. 글이 같으면 잇고, 다르면
-     * 이 행 id 를 단 이름은 충돌 전략을 따르고 · 자연 이름은 이은 노트가 없는 볼트에서만 충돌로 잇는다. 잇지 않으면 null.
-     * remote-first 는 `"write"` — 호출측이 받은 행으로 덮는다.
+     * 상태 기록에 없던 행 노트를 이 행과 다시 잇는다(P7) — 받은 글과 견줘 {@link relinkOutcome} 대로. 잇지 않으면 null.
+     * 원격으로 덮을 것은 `"write"` — 호출측이 받은 행으로 덮는다.
      */
     private relinkExistingRow;
+    /**
+     * dry-run — 실제 pull 이 상태 기록에 없던 이 행 노트를 다시 잇나(P7). 받은 행을 실제 pull 처럼 렌더하되 볼트 · 상태 DB 는
+     * 바꾸지 않고({@link ImageHandler.preview}) 견준다. 잇지 않으면 null(새 이름으로 받는다), 충돌로 남길 것이면 그 충돌.
+     */
+    private plannedRowRelink;
     /** 이번 받기에서 로컬 편집을 합친 행의 경로를 가져가고 비운다. */
     takeMergedRows(): string[];
     /**