@im-nobsidian/core 0.17.1 → 0.19.0

package/dist/index.d.ts

@@ -435,6 +435,8 @@ interface PushResult {
      * 겹치지 않는다. 예전에는 updated 에 섞여, 이름만 바꾼 노트도 「수정」 으로 보였다.
      */
     readonly moved: number;
+    /** 폴더 첨부로 올린 파일 수(ADR-054) — 노트 임베드는 노트와 함께 가 여기 들지 않는다. 없으면 0. */
+    readonly uploadedFiles?: number;
     readonly failed: FailedOperation[];
     readonly duration: number;
     /**
@@ -595,8 +597,9 @@ interface PullResult {
      */
     readonly relinkedPaths?: readonly string[];
     /**
-     * dry-run 만 — 상태 기록에 Notion 과 이은 노트가 없어 실제 pull 은 같은 자리의 노트를 먼저 다시 잇는다(P7). 미리 보기는
-     * 노트 글을 받아 견주지 않아 그 노트들도 {@link created} 로 센다. 이을 노트가 없으면 생략.
+     * dry-run 만 — {@link relinkedPaths} 는 이은 것이 아니라 실제 pull 이 다시 이을 것이다(P7). 미리 보기는 노트 글을 받아
+     * 견주지 않아 글이 다른 노트는 실제 pull 에서 충돌로 남는다. 자연 이름의 노트는 이은 노트가 없는 볼트에서만 이을 것으로
+     * 센다 — 이은 노트가 있는 볼트는 글이 같아야 잇는다. 이을 노트가 없으면 생략.
      */
     readonly relinkPending?: true;
     /**
@@ -2818,7 +2821,7 @@ declare class SyncOrchestrator {
      *   적어 push 가 올린다 — dry-run 은 받지 않아 원격이 바뀐 그대로라, 원격을 보고 거절하지 않는다.
      */
     /**
-     * @param relinkedByPull 같은 sync 의 dry-run pull 이 다시 이을 것이라고 미리 봤다 — 실제 sync 는 받으며 먼저 잇고 올리므로
+     * @param relinkedByPull 같은 sync 의 dry-run pull 이 받거나 다시 이을 것이 있다 — 실제 sync 는 받으며 먼저 잇고 올리므로
      *   상태 기록이 비었어도 막지 않는다({@link assertVaultLinked}).
      */
     private executePush;
@@ -3236,7 +3239,7 @@ declare class ImageHandler {
     /**
      * 임베드 경로가 가리킬 수 있는 볼트 실제 파일 후보를 우선순위대로 만든다(F23).
      * Obsidian 위키링크 임베드는 노트 옆 파일을 파일명만으로 참조하는 게 관례라
-     * 노트 폴더 → 볼트 루트 → attachments/ 순.
+     * 노트 폴더 → 볼트 루트 → attachments/ 순. 세 곳에 없으면 볼트 어디서든 이름으로 찾는다({@link VaultFileIndex}).
      *
      * push(업로드)와 pull(원본 복원)이 **같은 사다리**를 봐야 왕복이 닫힌다. 예전에는
      * pull 쪽이 볼트 루트만 확인해서, `__e2e_probe__/노트.md` 안의 `![[t-img.png]]` 는
@@ -3244,6 +3247,9 @@ declare class ImageHandler {
      * 새로 받았다(실측) — 왕복할 때마다 첨부가 한 벌씩 늘어난다.
      */
     private vaultCandidates;
+    private indexOfFiles;
+    /** 볼트의 첨부 이름표 — 처음 쓸 때 만든다. */
+    private get fileIndex();
     /**
      * 임베드 경로를 볼트 실제 파일로 해석해 읽는다(F23).
      * 폴백은 조용히 진행하고, 전부 실패했을 때만 마지막 오류를 던진다.
@@ -3255,6 +3261,8 @@ declare class ImageHandler {
     }>;
     private parseNotionFileUrl;
     private downloadFile;
+    /** 받은 파일의 이름 — `<줄기>-<해시><확장자>`. */
+    private fileNameOf;
     private isNotionImageUrl;
     private isNotionFileUrl;
     /**
@@ -3281,6 +3289,13 @@ declare class ImageHandler {
  */
 type NotionBlockType = "image" | "pdf" | "video" | "audio" | "file";
 
+/** 폴더 페이지에 실린 폴더 첨부 하나. */
+interface FolderFileRef {
+    readonly url: string;
+    /** 올린 파일 이름 — Notion 이 주소 끝에 싣는다. 받을 때 이 이름으로 쓴다. */
+    readonly name: string;
+}
+
 /** 첨부 다운로드 운영 튜닝값. 미지정 시 기존 동작과 동일한 기본값 사용. */
 interface FileHandlerOptions {
     /** 다운로드에 쓸 fetch 구현(테스트 주입용). 기본 전역 fetch. */
@@ -3289,6 +3304,21 @@ interface FileHandlerOptions {
     readonly downloadTimeoutMs?: number;
     /** 첨부 1건 업로드 전체의 시간 상한(ms). 기본 30분. 0 이하면 상한 없음. */
     readonly itemTimeoutMs?: number;
+    /**
+     * pull 이 받은 그림 · 파일을 두는 폴더(`paths.attachments`). 그 안의 파일은 폴더 첨부로 올리지 않는다 — 받은 것을
+     * 다시 올리면 Notion 에 사본이 생긴다.
+     */
+    readonly attachmentsFolder?: string;
+    /**
+     * 지운 폴더 첨부를 다른 쪽에서도 지우나(`sync.deleteSync`) — 볼트에서 지우면 Notion 의 블록을, Notion 에서 지우면 볼트의
+     * 파일을. 기본 false.
+     */
+    readonly deleteSync?: boolean;
+}
+/** 노트 없는 폴더의 Notion 페이지를 마련하는 쪽 — push 의 폴더 배치(`FolderPlacement`). */
+interface FolderPageProvider {
+    /** 폴더의 페이지를 마련한다. 이미 있으면 그대로 둔다. 마련할 수 없으면 까닭과 함께 던진다. */
+    ensureFolderPage(folder: string): Promise<void>;
 }
 interface FileUploadResult {
     readonly localPath: string;
@@ -3309,6 +3339,8 @@ declare class FileHandler {
     private readonly customFetch?;
     private readonly downloadTimeoutMs;
     private readonly itemTimeoutMs;
+    private readonly attachmentsFolder;
+    private readonly deleteSync;
     constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB, concurrency?: number, options?: FileHandlerOptions);
     private get fetchFn();
     pushFilesForFolder(folderPageId: string, folderPath: string): Promise<FileUploadResult[]>;
@@ -3329,6 +3361,12 @@ declare class FileHandler {
      * @returns 업로드 결과. 변경 없음(스킵)이거나 실패했으면 null.
      */
     private pushSingleFile;
+    /** 올린 뒤 바뀌지 않았나 — 크기가 같으면 읽지 않는다. */
+    private isUnchanged;
+    /** pull 이 받은 것을 두는 폴더 안인가. */
+    private inAttachmentsFolder;
+    /** 폴더 첨부를 둘 Notion 페이지 — 폴더 노트 없는 폴더의 페이지(폴더 레코드)만. 맨 위는 루트 기록이 있을 때만. */
+    private folderPageOf;
     /**
      * 업로드 후보 목록 — 도구 내부 산출물(`.base`/`.notion.json`)은 아예 빼고, Notion 이 받지 않는
      * 형식은 따로 모은다.
@@ -3347,7 +3385,43 @@ declare class FileHandler {
      * @param failed 올리지 못한 첨부를 담을 곳 — push 결과의 `failed` 를 넘기면 CLI · 플러그인이 처리하지 못한 것으로
      *   보인다. 예전엔 경고 로그로만 남아 push 가 「실패 0」 으로 끝났다.
      */
-    pushAllFiles(failed?: FailedOperation[]): Promise<FileUploadResult[]>;
+    pushAllFiles(failed?: FailedOperation[], folders?: FolderPageProvider): Promise<FileUploadResult[]>;
+    /**
+     * 볼트에서 지운 폴더 첨부를 Notion 에서도 지운다(deleteSync) — 폴더 페이지에 적힌 파일 가운데 볼트에 없는 것의 블록과 기록.
+     * 포함 · 제외 패턴으로 빠진 파일은 볼트에 있어 지우지 않는다.
+     */
+    private removeDeletedFolderFiles;
+    /** 폴더 첨부를 둘 페이지 — 노트 없는 폴더면 마련한다. 둘 곳이 없으면 그 파일들을 `stranded` 에 담고 null. */
+    private provideFolderPage;
+    /**
+     * 둘 곳이 없어 올리지 않은 폴더 첨부 — 경고로 알린다. 예전에는 디버그 로그로만 남아 파일이 Notion 에 가지 않은 것을 알 수
+     * 없었다. 노트에 붙이면 그 노트와 함께 올라간다.
+     */
+    private reportStranded;
+    /** 볼트의 노트가 붙인 파일 이름 — {@link embeddedNamesOf}. 읽지 못한 노트는 건너뛴다. */
+    private embeddedNames;
+    /**
+     * 폴더 페이지의 폴더 첨부를 그 폴더에 받는다 — 올린 이름 그대로. Notion 파일 id 가 적어 둔 것과 같으면(올린 볼트 · 앞서
+     * 받은 볼트) 받지 않는다. Notion 에서 바뀐 파일은 볼트 쪽이 그대로일 때만 덮는다 — 볼트에서도 고쳤으면 두고 알린다(다음
+     * push 가 볼트의 것을 올린다).
+     *
+     * @param complete 본문을 끝까지 받았나 — 그럴 때만 Notion 에서 지운 파일을 볼트에서 지운다(deleteSync). 잘린 본문에 없는
+     *   파일은 지운 것이 아니다.
+     * @returns 새로 받거나 바꾼 파일 수
+     */
+    receiveFolderFiles(folder: string, pageId: string, files: readonly FolderFileRef[], complete?: boolean): Promise<number>;
+    /**
+     * Notion 에서 지운 폴더 첨부를 볼트에서 지운다 — 지난 동기화 그대로일 때만. 볼트에서 고쳤으면 두고 기록만 놓는다 — 다음 push
+     * 가 다시 올린다(노트의 원격 삭제와 같은 규칙).
+     */
+    private removeLocalFolderFile;
+    /**
+     * 폴더 첨부 하나를 받는다. 볼트에 같은 경로가 있으면: 같은 내용이면 적기만 하고, 지난 동기화 뒤 볼트에서 그대로인 파일은
+     * 덮고(`entry`), 그 밖(볼트에서 고친 것 · 처음 보는 다른 파일)은 두고 알린다.
+     *
+     * @returns 볼트에 썼는가
+     */
+    private receiveOne;
     downloadFileBlock(url: string, filename: string, targetFolder: string): Promise<FileDownloadResult>;
     downloadFileBlocks(blocks: Array<{
         type: string;
@@ -3355,6 +3429,12 @@ declare class FileHandler {
         caption?: string;
     }>, targetFolder: string): Promise<FileDownloadResult[]>;
     private uploadFile;
+    /** 이 페이지에서 같은 이름의 파일 블록 중 방금 붙인 것 말고를 지운다. */
+    private removeOlderBlocks;
+    /**
+     * 폴더 첨부의 파일 블록 — 캡션에 파일 이름을 적는다. 받는 쪽이 그 표시로 폴더 첨부를 알아본다({@link folderFilesOf}) —
+     * 자식 페이지가 없는 폴더 페이지는 PDF 하나만 붙인 노트와 모양이 같다.
+     */
     private createFileBlock;
     private extractFilename;
 }
@@ -3564,6 +3644,8 @@ interface PlannedRow {
     readonly moves?: readonly RemoteMove[];
     /** 로컬도 고친 행을 실제 pull 이 받지 않는 까닭 — 없으면 받는다. */
     readonly resolution?: PlannedResolution;
+    /** `create` 만 — 상태 기록에 없던 같은 자리의 행 노트를 다시 잇는다(P7). 새로 받는 것으로 세지 않는다. */
+    readonly relink?: true;
 }
 /**
  * 로컬도 고친 노트를 실제 pull 이 어떻게 처리하나 — 충돌로 남김 · 합침(merge) · 받지 않음(원격이 그대로거나
@@ -3719,6 +3801,8 @@ declare class DatabaseSyncer {
          * 볼트에서 옮긴 레코드 — dry-run 은 옮겨 적지 않아 이동 WAL 이 없다. 실제 pull 처럼 볼트가 먼저다.
          */
         movingInVault?: ReadonlySet<string>;
+        /** 이번 미리 보기가 다시 이을 것으로 고른 자리({@link pathKey}) — 고르면 더한다. */
+        relinkTaken?: Set<string>;
     }): Promise<PlannedRow[]>;
     /**
      * 받은 행이 지난 사본 그대로인가 — 렌더한 글이 달라도 받을 것이 없으면 그 사이 로컬 편집을 충돌로 올리지 않는다
@@ -4031,7 +4115,8 @@ declare class WikilinkResolver implements Processor {
     process(input: ProcessorInput): ProcessorOutput;
     /**
      * `[[노트#제목]]` · `[[노트#^블록]]` · `[[#제목]]` → `[글자](https://www.notion.so/<페이지>#<블록>)`. 글자는 별칭,
-     * 없으면 Obsidian 이 보이는 「노트 > 제목」 — pull 이 그 글자면 별칭을 붙이지 않는다. 대상 페이지 · 블록을 못 찾으면 null.
+     * 없으면 Obsidian 이 보이는 「노트 > 제목」 — pull 이 그 글자면 별칭을 붙이지 않는다. 앵커 링크가 아니면 null, 못 풀면
+     * 그 까닭({@link AnchorMiss}).
      */
     private anchorLink;
 }