@remnic/core 1.1.15 → 1.1.16

package/src/access-service.ts

@@ -138,6 +138,7 @@ import {
 import {
   applyOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   type OfflineSyncApplyChangesetResult,
   type OfflineSyncSnapshot,
 } from "./offline-sync.js";
@@ -616,6 +617,13 @@ export interface EngramAccessOfflineSyncSnapshotRequest {
   includeContent?: boolean;
 }
 
+export interface EngramAccessOfflineSyncFilesRequest {
+  namespace?: string;
+  principal?: string;
+  includeTranscripts?: boolean;
+  paths: string[];
+}
+
 export interface EngramAccessOfflineSyncApplyRequest {
   namespace?: string;
   principal?: string;
@@ -626,6 +634,10 @@ export interface EngramAccessOfflineSyncSnapshotResponse extends OfflineSyncSnap
   namespace: string;
 }
 
+export interface EngramAccessOfflineSyncFilesResponse extends OfflineSyncSnapshot {
+  namespace: string;
+}
+
 export interface EngramAccessOfflineSyncApplyResponse extends OfflineSyncApplyChangesetResult {
   namespace: string;
 }
@@ -5568,6 +5580,38 @@ export class EngramAccessService {
     };
   }
 
+  async offlineSyncFiles(
+    options: EngramAccessOfflineSyncFilesRequest,
+  ): Promise<EngramAccessOfflineSyncFilesResponse> {
+    const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const storageHash = createHash("sha256").update(storage.dir).digest("hex").slice(0, 16);
+    try {
+      const snapshot = await buildOfflineSyncSnapshotForPaths({
+        root: storage.dir,
+        sourceId: `remnic:${resolvedNamespace}:${storageHash}`,
+        paths: options.paths,
+        includeContent: true,
+        includeTranscripts: options.includeTranscripts !== false,
+        readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+      });
+      return {
+        namespace: resolvedNamespace,
+        ...snapshot,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        message.startsWith("paths[]:") ||
+        message.startsWith("buildOfflineSyncSnapshotForPaths: record path ") ||
+        message.startsWith("offline sync snapshot path is excluded:")
+      ) {
+        throw new EngramAccessInputError(message);
+      }
+      throw error;
+    }
+  }
+
   async offlineSyncApply(
     options: EngramAccessOfflineSyncApplyRequest,
   ): Promise<EngramAccessOfflineSyncApplyResponse> {

package/src/index.ts

@@ -686,6 +686,7 @@ export {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
   normalizeOfflineSyncChangeset,

package/src/offline-sync.test.ts

@@ -9,6 +9,7 @@ import {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
 } from "./offline-sync.js";
 import { isEncryptedFile } from "./secure-store/secure-fs.js";
 import { StorageManager } from "./storage.js";
@@ -106,6 +107,130 @@ test("offline changeset pushes local edits when the remote is still at the share
   }
 });
 
+test("offline changeset only carries content for changed local files", async () => {
+  const local = await tempDir("remnic-offline-changeset-content");
+  try {
+    await write(local, "facts/unchanged.md", "same");
+    await write(local, "facts/changed.md", "before");
+    const base = await buildOfflineSyncSnapshot({
+      root: local,
+      sourceId: "remote",
+      includeContent: false,
+    });
+
+    await write(local, "facts/changed.md", "after");
+    await write(local, "facts/empty.md", "");
+    const changeset = await buildOfflineSyncChangeset({
+      root: local,
+      sourceId: "laptop",
+      baseFiles: base.files,
+    });
+
+    assert.deepEqual(
+      changeset.changes.map((change) => change.path),
+      ["facts/changed.md", "facts/empty.md"],
+    );
+    const empty = changeset.changes.find((change) => change.path === "facts/empty.md");
+    assert.equal(empty?.type, "upsert");
+    if (empty?.type === "upsert") {
+      assert.equal(empty.file.contentBase64, "");
+    }
+    assert.equal(JSON.stringify(changeset).includes("same"), false);
+  } finally {
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
+test("offline pull accepts metadata-only snapshots when files are unchanged", async () => {
+  const remote = await tempDir("remnic-offline-metadata-remote");
+  const local = await tempDir("remnic-offline-metadata-local");
+  try {
+    await write(remote, "facts/shared.md", "base");
+    const initial = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    const firstPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: initial,
+    });
+    const metadataOnly = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: false,
+    });
+
+    const secondPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: metadataOnly,
+      baseFiles: firstPull.nextBaseFiles,
+    });
+
+    assert.equal(secondPull.conflicts.length, 0);
+    assert.equal(secondPull.upserted, 0);
+    assert.equal(secondPull.skipped, 1);
+  } finally {
+    await rm(remote, { recursive: true, force: true });
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
+test("offline pull applies snapshots with content only for remote-changed files", async () => {
+  const remote = await tempDir("remnic-offline-partial-remote");
+  const local = await tempDir("remnic-offline-partial-local");
+  try {
+    await write(remote, "facts/shared.md", "base");
+    await write(remote, "facts/stable.md", "unchanged");
+    const initial = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    const firstPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: initial,
+    });
+
+    await write(remote, "facts/shared.md", "remote edit");
+    const metadataOnly = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: false,
+    });
+    const changedContent = await buildOfflineSyncSnapshotForPaths({
+      root: remote,
+      sourceId: "remote",
+      paths: ["facts/shared.md"],
+      includeContent: true,
+    });
+    const contentByPath = new Map(
+      changedContent.files.map((file) => [file.path, file.contentBase64]),
+    );
+    const hydrated = {
+      ...metadataOnly,
+      files: metadataOnly.files.map((file) => {
+        const contentBase64 = contentByPath.get(file.path);
+        return contentBase64 === undefined ? file : { ...file, contentBase64 };
+      }),
+    };
+
+    const secondPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: hydrated,
+      baseFiles: firstPull.nextBaseFiles,
+    });
+
+    assert.equal(secondPull.upserted, 1);
+    assert.equal(secondPull.conflicts.length, 0);
+    assert.equal(await readUtf8(local, "facts/shared.md"), "remote edit");
+    assert.equal(await readUtf8(local, "facts/stable.md"), "unchanged");
+  } finally {
+    await rm(remote, { recursive: true, force: true });
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
 test("offline pull preserves local edits when both sides changed since the base", async () => {
   const remote = await tempDir("remnic-offline-conflict-remote");
   const local = await tempDir("remnic-offline-conflict-local");

package/src/offline-sync.ts

@@ -127,6 +127,14 @@ export interface OfflineSyncFileWriteTarget extends OfflineSyncFileTarget {
   content: Buffer;
 }
 
+interface OfflineSyncFileRecordOptions {
+  root: SafeArchiveRoot;
+  relPath: string;
+  filePath: string;
+  includeContent: boolean;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}
+
 const SYNC_INTERNAL_DIR = ".offline-sync";
 const EXCLUDED_FILE_NAMES = new Set([
   ".sync-state.json",
@@ -406,6 +414,24 @@ function filterBaseFilesForMode(
   return files.filter((file) => !shouldExcludeRelPath(file.path, includeTranscripts));
 }
 
+async function readOfflineSyncFileRecord(
+  options: OfflineSyncFileRecordOptions,
+): Promise<OfflineSyncFileRecord> {
+  const relPath = validateArchiveRelativePath(options.relPath, "offlineSyncFile.path");
+  const bytes = options.readFile
+    ? await options.readFile({ root: options.root.abs, path: relPath, filePath: options.filePath })
+    : await readFile(options.filePath);
+  const digest = sha256Buffer(bytes);
+  const st = await stat(options.filePath);
+  return {
+    path: relPath,
+    sha256: digest.sha256,
+    bytes: digest.bytes,
+    mtimeMs: st.mtimeMs,
+    ...(options.includeContent ? { contentBase64: bytes.toString("base64") } : {}),
+  };
+}
+
 export async function buildOfflineSyncSnapshot(options: {
   root: string;
   sourceId: string;
@@ -432,18 +458,13 @@ export async function buildOfflineSyncSnapshot(options: {
         continue;
       }
       if (!entry.isFile()) continue;
-      const bytes = options.readFile
-        ? await options.readFile({ root: root.abs, path: relPosix, filePath: abs })
-        : await readFile(abs);
-      const digest = sha256Buffer(bytes);
-      const st = await stat(abs);
-      files.push({
-        path: validateArchiveRelativePath(relPosix, "buildOfflineSyncSnapshot"),
-        sha256: digest.sha256,
-        bytes: digest.bytes,
-        mtimeMs: st.mtimeMs,
-        ...(options.includeContent === true ? { contentBase64: bytes.toString("base64") } : {}),
-      });
+      files.push(await readOfflineSyncFileRecord({
+        root,
+        relPath: relPosix,
+        filePath: abs,
+        includeContent: options.includeContent === true,
+        readFile: options.readFile,
+      }));
     }
   }
 
@@ -459,6 +480,53 @@ export async function buildOfflineSyncSnapshot(options: {
   };
 }
 
+export async function buildOfflineSyncSnapshotForPaths(options: {
+  root: string;
+  sourceId: string;
+  paths: readonly string[];
+  includeContent?: boolean;
+  includeTranscripts?: boolean;
+  now?: Date;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}): Promise<OfflineSyncSnapshot> {
+  const rootAbs = path.resolve(options.root);
+  const root = await prepareSafeArchiveRoot(rootAbs, "buildOfflineSyncSnapshotForPaths", "root");
+  const includeTranscripts = options.includeTranscripts !== false;
+  const files: OfflineSyncFileRecord[] = [];
+  const seen = new Set<string>();
+
+  for (const rawPath of options.paths) {
+    const relPath = normalizeRelativePath(rawPath, "paths[]");
+    if (seen.has(relPath)) continue;
+    seen.add(relPath);
+    if (shouldExcludeRelPath(relPath, includeTranscripts)) {
+      throw new Error(`offline sync snapshot path is excluded: ${relPath}`);
+    }
+    const filePath = await resolveSafeArchiveTarget(root, relPath);
+    const st = await lstat(filePath).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    });
+    if (!st || st.isSymbolicLink() || !st.isFile()) continue;
+    files.push(await readOfflineSyncFileRecord({
+      root,
+      relPath,
+      filePath,
+      includeContent: options.includeContent === true,
+      readFile: options.readFile,
+    }));
+  }
+
+  return {
+    format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+    schemaVersion: 1,
+    createdAt: (options.now ?? new Date()).toISOString(),
+    sourceId: normalizeSourceId(options.sourceId, "sourceId"),
+    includeTranscripts,
+    files: files.sort(compareByPath),
+  };
+}
+
 export async function buildOfflineSyncChangeset(options: {
   root: string;
   sourceId: string;
@@ -475,7 +543,7 @@ export async function buildOfflineSyncChangeset(options: {
   const current = await buildOfflineSyncSnapshot({
     root: options.root,
     sourceId: options.sourceId,
-    includeContent: true,
+    includeContent: false,
     includeTranscripts,
     now: options.now,
     readFile: options.readFile,
@@ -487,11 +555,24 @@ export async function buildOfflineSyncChangeset(options: {
     const baseEntry = base.get(relPath);
     const currentEntry = currentMap.get(relPath);
     if (currentEntry && currentEntry.sha256 !== baseEntry?.sha256) {
+      const file = await buildOfflineSyncSnapshotForPaths({
+        root: options.root,
+        sourceId: options.sourceId,
+        paths: [relPath],
+        includeContent: true,
+        includeTranscripts,
+        now: options.now,
+        readFile: options.readFile,
+      });
+      const record = file.files[0];
+      if (!record || typeof record.contentBase64 !== "string" || record.sha256 !== currentEntry.sha256) {
+        throw new Error(`offline sync file changed while building changeset: ${relPath}`);
+      }
       changes.push({
         type: "upsert",
         path: relPath,
         ...(baseEntry ? { baseSha256: baseEntry.sha256 } : {}),
-        file: currentEntry as OfflineSyncFileRecord & { contentBase64: string },
+        file: record as OfflineSyncFileRecord & { contentBase64: string },
       });
       continue;
     }
@@ -535,13 +616,15 @@ export async function applyOfflineSyncSnapshot(options: {
   writeFile?: (target: OfflineSyncFileWriteTarget) => Promise<void>;
   deleteFile?: (target: OfflineSyncFileTarget) => Promise<void>;
 }): Promise<OfflineSyncApplySnapshotResult> {
-  const snapshot = normalizeOfflineSyncSnapshot(options.snapshot, { requireContent: true });
+  const snapshot = normalizeOfflineSyncSnapshot(options.snapshot);
   const baseMap = byPath(filterBaseFilesForMode(
     normalizeFileStates(options.baseFiles),
     snapshot.includeTranscripts,
   ));
   const incomingMap = byPath(snapshot.files);
-  const incomingBuffers = verifyRecordContents(snapshot.files, "offline sync snapshot");
+  const incomingBuffers = verifyRecordContents(snapshot.files, "offline sync snapshot", {
+    requireContent: false,
+  });
   const root = await ensureSyncRoot(options.root, "applyOfflineSyncSnapshot");
   const current = await buildOfflineSyncSnapshot({
     root: root.abs,
@@ -582,7 +665,9 @@ export async function applyOfflineSyncSnapshot(options: {
           reason: "local_deleted_remote_modified",
           baseSha256: base.sha256,
           incomingSha256: incoming.sha256,
-          incomingBuffer: incomingBuffers.get(relPath),
+          incomingBuffer: options.writeConflictCopies === false
+            ? incomingBuffers.get(relPath)
+            : requiredBuffer(incomingBuffers, relPath),
           writeConflictCopies: options.writeConflictCopies !== false,
           sourceId: snapshot.sourceId,
           writeFile: options.writeFile,
@@ -615,7 +700,9 @@ export async function applyOfflineSyncSnapshot(options: {
         baseSha256: base?.sha256,
         localSha256: currentEntry?.sha256,
         incomingSha256: incoming.sha256,
-        incomingBuffer: incomingBuffers.get(relPath),
+        incomingBuffer: options.writeConflictCopies === false
+          ? incomingBuffers.get(relPath)
+          : requiredBuffer(incomingBuffers, relPath),
         writeConflictCopies: options.writeConflictCopies !== false,
         sourceId: snapshot.sourceId,
         writeFile: options.writeFile,
@@ -774,10 +861,12 @@ export async function applyOfflineSyncChangeset(options: {
 function verifyRecordContents(
   records: readonly OfflineSyncFileRecord[],
   context: string,
+  options: { requireContent?: boolean } = {},
 ): Map<string, Buffer> {
   const buffers = new Map<string, Buffer>();
   for (const record of records) {
     if (typeof record.contentBase64 !== "string") {
+      if (options.requireContent === false) continue;
       throw new Error(`${context}: contentBase64 is required for ${record.path}`);
     }
     const buffer = Buffer.from(record.contentBase64, "base64");