@im-nobsidian/core 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -1578,6 +1578,11 @@ interface NotionClientOptions {
     readonly notifications?: NotificationMode;
     readonly fetch?: typeof globalThis.fetch;
 }
+/** 덧붙일 자리 — 블록 뒤(`after`) · 맨 앞(`atStart`). 없으면 맨 끝. */
+interface AppendPosition {
+    readonly after?: string;
+    readonly atStart?: boolean;
+}
 declare class NotionClient {
     private readonly client;
     private readonly sema;
@@ -1880,31 +1885,31 @@ declare class NotionClient {
      */
     getBlockTree(blockId: string): Promise<BlockTreeNode[]>;
     /**
-     * 자식 블록을 덧붙인다. `options.after` 를 주면 그 블록 **바로 뒤**에 삽입한다
+     * 자식 블록을 덧붙인다. `options.after` 를 주면 그 블록 **바로 뒤**에, `options.atStart` 면 맨 앞에 삽입한다
      * (기본은 맨 끝). 자리표시자를 실제 미디어 블록으로 제자리 교체할 때 필요하다.
      *
      * 실측(2025-09-03): position 삽입 응답의 `results` 는 방금 넣은 블록뿐 아니라
      * 삽입 지점 이후의 형제까지 함께 돌려준다. 앞에서부터 batch 길이만큼이 새 블록이므로
      * 배치를 이어 붙일 때는 그 마지막 id 를 다음 기준점으로 삼는다.
      */
-    appendChildren(blockId: string, children: unknown[], options?: {
-        readonly after?: string;
-    }): Promise<string[]>;
+    appendChildren(blockId: string, children: unknown[], options?: AppendPosition): Promise<string[]>;
     /**
      * {@link appendChildren} 과 같되 새로 만든 블록을 통째로 돌려준다. 파일을 붙인 미디어 블록은
      * 응답에 Notion 이 저장한 파일의 URL 이 실려 온다 — 다시 조회하지 않고 그 파일을 알아 둔다(S-05).
      */
-    appendChildBlocks(blockId: string, children: unknown[], options?: {
-        readonly after?: string;
-    }): Promise<(BlockObjectResponse | PartialBlockObjectResponse)[]>;
+    appendChildBlocks(blockId: string, children: unknown[], options?: AppendPosition): Promise<(BlockObjectResponse | PartialBlockObjectResponse)[]>;
     /**
      * 깊이 제한 없는 블록 트리를 맨 끝에 덧붙인다 — 요청 한도(깊이 두 단계 · 100 개 · 1000 블록)를 넘는
      * 자식은 부모를 만든 뒤 그 아래에 마저 붙인다({@link shapeAppendRequests}). 더 깊은 블록의 id 는
      * 응답에 없어 부모의 자식 목록을 읽어 찾는다.
      *
+     * `options.atStart` 면 맨 위 블록을 맨 앞에 넣는다 — 본문 뒤에 둘 블록(폴더 첨부)을 남기고 본문만 바꿀 때.
+     *
      * 중간에 실패하면 그때까지 만든 블록은 남는다 — 호출측이 실패로 알린다.
      */
-    appendBlockTree(parentId: string, blocks: readonly BlockRequest[]): Promise<void>;
+    appendBlockTree(parentId: string, blocks: readonly BlockRequest[], options?: {
+        readonly atStart?: boolean;
+    }): Promise<void>;
     deleteBlock(blockId: string): Promise<void>;
     /**
      * 코드 블록의 글을 바꾼다 — Markdown API 로 보낼 수 없는 코드(코드 속 ``` 줄, S-22)를 블록으로
@@ -2821,6 +2826,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 은 받지 않아 원격이 바뀐 그대로라, 원격을 보고 거절하지 않는다.
@@ -3329,6 +3340,21 @@ interface FileHandlerOptions {
      * 파일을. 기본 false.
      */
     readonly deleteSync?: boolean;
+    /**
+     * 볼트 맨 위 파일을 싣는 페이지({@link rootFilesPageOf}) — 페이지 모드의 루트. 없으면(DB 모드) 볼트 맨 위 파일은 경고로 남는다.
+     * 루트는 사용자의 페이지라 노트 페이지처럼 적어 둔 폴더 첨부만 제 것으로 본다.
+     */
+    readonly rootPageId?: string | null;
+}
+/**
+ * 노트의 페이지에 폴더 첨부 블록을 붙이거나 지울 때(ADR-056) — 그 쓰기로 노트 페이지의 수정 시각 · 본문이 바뀐다. 알리지 않으면
+ * 다음 push 가 그 노트를 «Notion 에서도 바뀐 페이지» 로 보고 올리지 않는다.
+ */
+interface NotePageWrites {
+    /** 쓰기 전 — 그 노트가 지금 원격과 맞는지 본다. */
+    begin(pageId: string): Promise<void>;
+    /** 쓴 뒤 — 맞던 노트는 지금 원격을 본 것으로 적는다. 맞지 않던 노트(받지 않은 Notion 편집)는 그대로 둔다. */
+    end(pageId: string): Promise<void>;
 }
 /** 노트 없는 폴더의 Notion 페이지를 마련하는 쪽 — push 의 폴더 배치(`FolderPlacement`). */
 interface FolderPageProvider {
@@ -3356,6 +3382,7 @@ declare class FileHandler {
     private readonly itemTimeoutMs;
     private readonly attachmentsFolder;
     private readonly deleteSync;
+    private readonly rootPageId;
     constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB, concurrency?: number, options?: FileHandlerOptions);
     private get fetchFn();
     pushFilesForFolder(folderPageId: string, folderPath: string): Promise<FileUploadResult[]>;
@@ -3376,12 +3403,31 @@ 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/행/`)는 그 행의 페이지 끝. DB 폴더는 둘 곳이 없다 — Notion 의 DB 는 본문이 없다.
+     */
     private folderPageOf;
+    /**
+     * 이 폴더를 품은 노트의 페이지 — 폴더 노트 · 노트(행 포함) 이름의 폴더 · 볼트 맨 위는 루트 페이지. 본문이 이 도구의 것이
+     * 아니거나(루트) 노트의 것이라, 적어 둔 폴더 첨부만 제 것으로 본다. 없으면 null.
+     */
+    private notePageOf;
+    private folderRecordPageOf;
+    /**
+     * 이 기록이 그 폴더의 폴더 첨부인가. 노트의 페이지에는 그 노트가 임베드해 올린 파일도 같은 페이지로 적혀 있다 — 폴더
+     * 첨부로 적어 둔 것({@link folderFileIdsOf})만이다.
+     */
+    private isFolderFileEntry;
     /**
      * 업로드 후보 목록 — 도구 내부 산출물(`.base`/`.notion.json`)은 아예 빼고, Notion 이 받지 않는
      * 형식은 따로 모은다.
@@ -3400,12 +3446,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;
     /**
@@ -3444,11 +3492,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;
@@ -3683,6 +3743,11 @@ interface RowProgress {
     planned(count: number): void;
     done(item: ProgressItem): void;
 }
+/** 행 페이지 끝에서 뗀 폴더 첨부 — `complete` 면 빠진 파일을 Notion 에서 지운 것으로 본다. */
+interface RowFolderFiles {
+    readonly files: readonly FolderFileRef[];
+    readonly complete: boolean;
+}
 declare class DatabaseSyncer {
     private readonly config;
     private readonly stateDb;
@@ -3700,6 +3765,8 @@ declare class DatabaseSyncer {
      * 채운다({@link RemoteDetector.noteBodyChildren}).
      */
     private readonly noteRowBody;
+    /** 행 이름의 폴더에 그 행 페이지의 폴더 첨부를 받는다(ADR-056) — `PagePuller.receiveFolderFiles`. */
+    private readonly receiveRowFiles;
     private readonly propertyMapper;
     private decorationsCache?;
     /**
@@ -3759,7 +3826,9 @@ declare class DatabaseSyncer {
      * 받은 행 본문(Notion 원문)을 알린다 — 감지가 행의 하위 페이지를 빠뜨렸을 때 그 본문의 자식 태그로
      * 채운다({@link RemoteDetector.noteBodyChildren}).
      */
-    noteRowBody?: (pageId: string, rawMarkdown: string) => void);
+    noteRowBody?: (pageId: string, rawMarkdown: string) => void, 
+    /** 행 이름의 폴더에 그 행 페이지의 폴더 첨부를 받는다(ADR-056) — `PagePuller.receiveFolderFiles`. */
+    receiveRowFiles?: (folder: string, pageId: string, files: readonly FolderFileRef[], complete: boolean) => Promise<void>);
     pullAll(opts?: {
         readonly paths?: readonly string[];
         readonly progress?: RowProgress;
@@ -4021,6 +4090,8 @@ declare class DatabaseSyncer {
         bodyFingerprint: string;
         /** 원격 본문에 페이지 시절의 속성 블록이 있었나 — 받으며 걷어 냈다. */
         propertiesBlock: boolean;
+        /** 행 끝에서 뗀 폴더 첨부(ADR-056 · 행 이름의 폴더) — 받는 것은 호출측이 정한다. */
+        folderFiles: RowFolderFiles;
     }>;
     /**
      * 행의 본문 밖이 지난 동기화 사본 그대로인가(N-05) — 제목과 보낼 수 있는 속성, 아이콘 · 커버.
@@ -4107,6 +4178,11 @@ declare class DatabaseSyncer {
      * 든다. 추적하는 노트가 없으면 null.
      */
     private adoptedChildrenOf;
+    /**
+     * 이 노트 · 행 옆의 폴더(`from`)가 그것의 것인가 — 하위 페이지가 있거나, 그 페이지에 올린 폴더 첨부(ADR-056)가 든 폴더.
+     * 예전에는 하위 페이지만 보아 행의 이름을 따라 옮길 때 폴더 첨부만 든 폴더가 옛 이름에 남았다.
+     */
+    private holdsChildren;
     /**
      * Notion 에서 바꾼 제목으로 행 이름을 바꿀 자리(`sync.renameOnTitleChange`) — 바꿀 것이 없으면 null.
      * 받기 · pull dry-run · status 가 같은 판정을 쓴다. 행의 하위 페이지 폴더(`행/`)도 새 이름으로 옮기며, 옮길 수
@@ -4118,7 +4194,12 @@ declare class DatabaseSyncer {
     } | {
         reason: string;
     } | null>;
+    /**
+     * 행 하나를 받고 그 행 페이지의 폴더 첨부를 행 이름의 폴더에 받는다(ADR-056) — 노트가 충돌로 남거나 로컬을 지켜도 파일은
+     * 제 규칙대로 받는다(페이지와 같다). 행을 옮겼으면 옮긴 자리로.
+     */
     private pullDatabasePage;
+    private pullDatabaseRow;
 }
 
 declare class FrontmatterExtractor implements Processor {