@agent-native/core 0.164.12 → 0.164.15

package/corpus/templates/content/app/lib/local-content-source-files.ts

@@ -6,6 +6,11 @@ import {
 } from "@shared/content-source";
 
 import { getDesktopContentFiles } from "./desktop-content-files";
+import type {
+  DesktopContentFileRevision,
+  DesktopContentFilesChange,
+  DesktopContentFilesFolder,
+} from "./desktop-content-files";
 
 type PermissionState = "granted" | "denied" | "prompt";
 type LocalWritable = {
@@ -57,8 +62,18 @@ export type LocalSourceFileResult =
       path: string;
       absolutePath?: string;
       runtime: "browser" | "desktop" | "server-local";
+      revision?: DesktopContentFileRevision;
     }
-  | { ok: false; error: string; unavailable?: boolean };
+  | {
+      ok: false;
+      error: string;
+      unavailable?: boolean;
+      conflict?: {
+        path: string;
+        expectedRevision?: string | null;
+        actualRevision?: DesktopContentFileRevision;
+      };
+    };
 
 export type LocalSourceDocumentReadResult =
   | {
@@ -68,9 +83,23 @@ export type LocalSourceDocumentReadResult =
       document: Document;
       updatedAt: string;
       runtime: "browser" | "desktop";
+      revision?: DesktopContentFileRevision;
     }
   | { ok: false; error: string; unavailable?: boolean };
 
+export type LinkedLocalSourceChange = DesktopContentFilesChange & {
+  sourcePath: string;
+};
+
+export type LinkedLocalSourceWatchResult =
+  | { ok: true; unsubscribe(): void }
+  | { ok: false; error: string; unavailable?: boolean };
+
+export type LinkedLocalSourceWriteOptions = {
+  /** Opaque revision observed when the editor loaded the physical file. */
+  expectedRevision?: string;
+};
+
 const LOCAL_FILES_DB_NAME = "content-local-files";
 const LOCAL_FILES_DB_VERSION = 1;
 const LOCAL_FILES_STORE_NAME = "handles";
@@ -211,7 +240,10 @@ async function resolveBrowserSourceForPath(filePath: string) {
   };
 }
 
-async function resolveDesktopSourceForPath(filePath: string) {
+async function resolveDesktopSourceForPath(
+  filePath: string,
+  source?: DocumentSourceInfo,
+) {
   const desktopFiles = getDesktopContentFiles();
   if (!desktopFiles) return null;
   const result = await desktopFiles.getFolder();
@@ -220,7 +252,31 @@ async function resolveDesktopSourceForPath(filePath: string) {
     result.folders && result.folders.length > 0
       ? result.folders
       : [result.folder];
+  const sourceFolder = source?.rootPath
+    ? folders.find(
+        (folder) =>
+          folder.id === source.rootPath ||
+          folder.sourcePrefix === source.rootPath ||
+          folder.name === source.rootPath,
+      )
+    : undefined;
+  if (sourceFolder) {
+    return { api: desktopFiles, folder: sourceFolder, path: filePath };
+  }
   const resolved = resolveSourcePathForFolders(filePath, folders);
+  if (!resolved && folders.length > 1) {
+    const matches: DesktopContentFilesFolder[] = [];
+    for (const folder of folders) {
+      if (!folder.id) continue;
+      const read = await desktopFiles.readFiles({ folderId: folder.id });
+      if (read.ok && read.sources?.[filePath] !== undefined) {
+        matches.push(folder);
+      }
+    }
+    if (matches.length === 1) {
+      return { api: desktopFiles, folder: matches[0]!, path: filePath };
+    }
+  }
   if (!resolved) {
     throw new Error(`Local source folder for "${filePath}" was not found.`);
   }
@@ -295,23 +351,24 @@ async function readBrowserFile(root: LocalDirectoryHandle, filePath: string) {
   };
 }
 
-function joinDesktopAbsolutePath(folderPath: string, filePath: string) {
-  const folder = folderPath.replace(/[\\/]+$/, "");
-  const separator = folder.includes("\\") ? "\\" : "/";
-  const folderParts = folder.split(/[\\/]/).filter(Boolean);
-  const folderName = folderParts[folderParts.length - 1];
-  let relativePath = filePath;
-  if (
-    folderName === CONTENT_SOURCE_ROOT &&
-    relativePath.startsWith(`${CONTENT_SOURCE_ROOT}/`)
-  ) {
-    relativePath = relativePath.slice(CONTENT_SOURCE_ROOT.length + 1);
-  }
-  return `${folder}${separator}${relativePath.replace(/\//g, separator)}`;
-}
-
-function sourceFileContent(document: Document) {
-  return serializeContentSourceDocument({
+const MANAGED_SOURCE_FRONTMATTER_KEYS = new Set([
+  "id",
+  "title",
+  "description",
+  "parentId",
+  "icon",
+  "position",
+  "isFavorite",
+  "hideFromSearch",
+  "visibility",
+  "updatedAt",
+]);
+
+const SOURCE_FRONTMATTER_RE =
+  /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n\r?\n|\r?\n|$)/;
+
+export function sourceFileContent(document: Document, existingSource?: string) {
+  const serialized = serializeContentSourceDocument({
     id: document.id,
     parentId: document.parentId,
     title: document.title,
@@ -323,6 +380,19 @@ function sourceFileContent(document: Document) {
     visibility: document.visibility,
     updatedAt: document.updatedAt,
   });
+  const existingFrontmatter = existingSource?.match(SOURCE_FRONTMATTER_RE)?.[1];
+  if (!existingFrontmatter) return serialized;
+
+  const preservedLines = existingFrontmatter.split(/\r?\n/).filter((line) => {
+    const key = line.match(/^([A-Za-z][A-Za-z0-9_-]*):/)?.[1];
+    return !key || !MANAGED_SOURCE_FRONTMATTER_KEYS.has(key);
+  });
+  if (preservedLines.length === 0) return serialized;
+
+  return serialized.replace(
+    "\n---\n\n",
+    `\n${preservedLines.join("\n")}\n---\n\n`,
+  );
 }
 
 function documentFromSourceContent(input: {
@@ -378,6 +448,7 @@ export function canWriteLinkedLocalSource(
 export async function writeDocumentToLinkedLocalSource(
   document: Document,
   source: DocumentSourceInfo | undefined = document.source,
+  options: LinkedLocalSourceWriteOptions = {},
 ): Promise<LocalSourceFileResult> {
   const filePath = normalizeSourcePath(source?.path);
   if (!filePath) {
@@ -395,22 +466,56 @@ export async function writeDocumentToLinkedLocalSource(
     };
   }
 
-  const content = sourceFileContent(document);
-  const desktopSource = await resolveDesktopSourceForPath(filePath);
+  const desktopSource = await resolveDesktopSourceForPath(filePath, source);
   if (desktopSource) {
+    const current = await desktopSource.api.readFiles({
+      folderId: desktopSource.folder.id,
+    });
+    if (!current.ok) {
+      return { ok: false, error: current.error };
+    }
+    const existingSource = current.sources?.[desktopSource.path];
+    if (existingSource === undefined) {
+      return {
+        ok: false,
+        error: `Local file "${filePath}" was not found.`,
+      };
+    }
+    const content = sourceFileContent(document, existingSource);
+    const expectedRevision =
+      options.expectedRevision ?? current.revisions?.[desktopSource.path];
+    if (!expectedRevision) {
+      return {
+        ok: false,
+        error: `Local file "${filePath}" has no observed revision.`,
+      };
+    }
     const result = await desktopSource.api.writeFile({
       folderId: desktopSource.folder.id,
       path: desktopSource.path,
       content,
+      expectedRevision,
     });
-    if (!result.ok) return { ok: false, error: result.error };
+    if (!result.ok) {
+      return {
+        ok: false,
+        error: result.error,
+        unavailable: result.code === "unavailable",
+        conflict:
+          result.code === "conflict" && result.conflict
+            ? {
+                path: filePath,
+                expectedRevision: result.conflict.expectedRevision,
+                actualRevision: result.conflict.actualRevision,
+              }
+            : undefined,
+      };
+    }
     return {
       ok: true,
       path: filePath,
-      absolutePath: result.folder.path
-        ? joinDesktopAbsolutePath(result.folder.path, desktopSource.path)
-        : undefined,
       runtime: "desktop",
+      revision: result.revisions?.[desktopSource.path],
     };
   }
 
@@ -429,10 +534,80 @@ export async function writeDocumentToLinkedLocalSource(
       error: "Write permission was not granted for the source folder.",
     };
   }
+  const existingSource = await readBrowserFile(
+    browserSource.handle,
+    browserSource.path,
+  );
+  const content = sourceFileContent(document, existingSource.content);
   await writeBrowserFile(browserSource.handle, browserSource.path, content);
   return { ok: true, path: filePath, runtime: "browser" };
 }
 
+/**
+ * Subscribe only through an already-authorized Desktop grant. Browser folder
+ * handles intentionally have no ambient watcher capability.
+ */
+export async function watchLinkedLocalSource(
+  source: DocumentSourceInfo | undefined,
+  onChange: (change: LinkedLocalSourceChange) => void,
+): Promise<LinkedLocalSourceWatchResult> {
+  const filePath = normalizeSourcePath(source?.path);
+  if (!filePath) {
+    return {
+      ok: false,
+      error: "This document is not linked to a source file.",
+    };
+  }
+  const desktopSource = await resolveDesktopSourceForPath(filePath, source);
+  if (desktopSource?.api.watchFiles) {
+    return desktopSource.api.watchFiles(
+      { folderId: desktopSource.folder.id },
+      (change) => {
+        const legacyChange = change as DesktopContentFilesChange & {
+          path?: string;
+          previousPath?: string;
+        };
+        if (
+          legacyChange.path !== desktopSource.path &&
+          legacyChange.previousPath !== desktopSource.path
+        ) {
+          return;
+        }
+        onChange({ ...change, sourcePath: filePath });
+      },
+    );
+  }
+  if (
+    !desktopSource?.api.subscribeChanges ||
+    !desktopSource.api.unsubscribeChanges ||
+    !desktopSource.api.onChange
+  ) {
+    return {
+      ok: false,
+      unavailable: true,
+      error:
+        "Live local file updates require a current Agent Native Desktop bridge.",
+    };
+  }
+  const subscribed = await desktopSource.api.subscribeChanges({
+    folderId: desktopSource.folder.id,
+  });
+  if (!subscribed.ok) return { ok: false, error: subscribed.error };
+  const removeListener = desktopSource.api.onChange((change) => {
+    if (change.folderId !== desktopSource.folder.id) return;
+    onChange({ ...change, sourcePath: filePath });
+  });
+  return {
+    ok: true,
+    unsubscribe: () => {
+      removeListener();
+      void desktopSource.api.unsubscribeChanges?.({
+        folderId: desktopSource.folder.id,
+      });
+    },
+  };
+}
+
 export async function readDocumentFromLinkedLocalSource(
   document: Document,
   source: DocumentSourceInfo | undefined = document.source,
@@ -453,7 +628,7 @@ export async function readDocumentFromLinkedLocalSource(
     };
   }
 
-  const desktopSource = await resolveDesktopSourceForPath(filePath);
+  const desktopSource = await resolveDesktopSourceForPath(filePath, source);
   if (desktopSource) {
     const result = await desktopSource.api.readFiles({
       folderId: desktopSource.folder.id,
@@ -471,7 +646,13 @@ export async function readDocumentFromLinkedLocalSource(
       content,
       updatedAt,
     });
-    return read.ok ? { ...read, runtime: "desktop" } : read;
+    return read.ok
+      ? {
+          ...read,
+          runtime: "desktop",
+          revision: result.revisions?.[desktopSource.path],
+        }
+      : read;
   }
 
   const browserSource = await resolveBrowserSourceForPath(filePath);
@@ -521,9 +702,7 @@ export async function localSourceAbsolutePath(
   if (!filePath) return source?.absolutePath ?? null;
   if (source?.absolutePath) return source.absolutePath;
 
-  const desktopSource = await resolveDesktopSourceForPath(filePath);
-  if (!desktopSource?.folder.path) return null;
-  return joinDesktopAbsolutePath(desktopSource.folder.path, desktopSource.path);
+  return null;
 }
 
 export async function revealLinkedLocalSourceFile(
@@ -537,7 +716,7 @@ export async function revealLinkedLocalSourceFile(
     };
   }
 
-  const desktopSource = await resolveDesktopSourceForPath(filePath);
+  const desktopSource = await resolveDesktopSourceForPath(filePath, source);
   if (!desktopSource) {
     return {
       ok: false,
@@ -554,9 +733,6 @@ export async function revealLinkedLocalSourceFile(
   return {
     ok: true,
     path: filePath,
-    absolutePath: result.folder.path
-      ? joinDesktopAbsolutePath(result.folder.path, desktopSource.path)
-      : undefined,
     runtime: "desktop",
   };
 }

package/corpus/templates/content/app/lib/local-folder-live-sync.ts

@@ -0,0 +1,191 @@
+import { callAction } from "@agent-native/core/client/hooks";
+
+import type { DesktopContentFilesFolder } from "./desktop-content-files";
+import { getDesktopContentFiles } from "./desktop-content-files";
+
+const REGISTRY_KEY = "content-local-folder-live-sources-v1";
+const ACTIVATION_EVENT = "content-local-folder-working-copy-activation";
+
+let requestedWorkingCopyId: string | null = null;
+
+interface LiveLocalFolderSource {
+  folderId: string;
+  sourceId: string;
+  databaseId?: string;
+  repositoryId?: string;
+}
+
+function readRegistry(): LiveLocalFolderSource[] {
+  if (typeof window === "undefined") return [];
+  try {
+    const value = JSON.parse(window.localStorage.getItem(REGISTRY_KEY) ?? "[]");
+    if (!Array.isArray(value)) return [];
+    return value.filter(
+      (entry): entry is LiveLocalFolderSource =>
+        typeof entry?.folderId === "string" &&
+        typeof entry?.sourceId === "string" &&
+        (entry.databaseId === undefined ||
+          typeof entry.databaseId === "string") &&
+        (entry.repositoryId === undefined ||
+          typeof entry.repositoryId === "string"),
+    );
+  } catch {
+    // coercion-ok: corrupt device-local cache is treated as an absent optional registry
+    return [];
+  }
+}
+
+export async function rememberLiveLocalFolderSource(
+  folder: DesktopContentFilesFolder,
+  sourceId: string,
+  databaseId?: string | null,
+) {
+  if (!folder.id || typeof window === "undefined") return;
+  const next = [
+    ...readRegistry().filter((entry) => entry.folderId !== folder.id),
+    {
+      folderId: folder.id,
+      sourceId,
+      ...(databaseId ? { databaseId } : {}),
+      ...(folder.repository?.localId
+        ? { repositoryId: folder.repository.localId }
+        : {}),
+    },
+  ];
+  window.localStorage.setItem(REGISTRY_KEY, JSON.stringify(next));
+  const persisted = await getDesktopContentFiles()?.associateSource?.({
+    folderId: folder.id,
+    sourceId,
+    ...(databaseId ? { databaseId } : {}),
+  });
+  if (persisted && !persisted.ok) throw new Error(persisted.error);
+}
+
+export function forgetLiveLocalFolderSource(folderId: string) {
+  if (typeof window === "undefined") return;
+  const next = readRegistry().filter((entry) => entry.folderId !== folderId);
+  window.localStorage.setItem(REGISTRY_KEY, JSON.stringify(next));
+}
+
+export function liveLocalFolderSourceId(folderId: string) {
+  return readRegistry().find((entry) => entry.folderId === folderId)?.sourceId;
+}
+
+export function requestLiveLocalFolderActivation(folderId: string) {
+  requestedWorkingCopyId = folderId;
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent(ACTIVATION_EVENT, { detail: folderId }),
+    );
+  }
+}
+
+export function pendingLiveLocalFolderActivation() {
+  return requestedWorkingCopyId;
+}
+
+export function consumeLiveLocalFolderActivation(folderId: string) {
+  if (requestedWorkingCopyId === folderId) requestedWorkingCopyId = null;
+}
+
+export function subscribeLiveLocalFolderActivation(
+  callback: (folderId: string) => void,
+) {
+  if (typeof window === "undefined") return () => {};
+  const listener = (event: Event) => {
+    const folderId = (event as CustomEvent<unknown>).detail;
+    if (typeof folderId === "string") callback(folderId);
+  };
+  window.addEventListener(ACTIVATION_EVENT, listener);
+  return () => window.removeEventListener(ACTIVATION_EVENT, listener);
+}
+
+export async function connectTemporaryLocalFolder(
+  folder: DesktopContentFilesFolder,
+) {
+  if (!folder.id || folder.kind !== "temporary") return null;
+  const existing = readRegistry().find((entry) => entry.folderId === folder.id);
+  if (
+    existing?.repositoryId &&
+    existing.repositoryId === folder.repository?.localId
+  ) {
+    return existing.sourceId;
+  }
+  if (existing) forgetLiveLocalFolderSource(folder.id);
+  const persistent = readRegistry().find(
+    (entry) =>
+      entry.databaseId &&
+      entry.repositoryId &&
+      entry.repositoryId === folder.repository?.localId,
+  );
+  if (!persistent?.databaseId) return null;
+  const connection = await callAction<{
+    sourceId: string | null;
+    filesDatabaseId: string | null;
+  }>(
+    "connect-local-folder-source" as never,
+    {
+      connectionId: folder.id,
+      label: folder.name,
+      databaseId: persistent.databaseId,
+      truthPolicy: "source_primary",
+      connectionMetadata: {
+        liveBridgeEnabled: true,
+        repository: folder.repository
+          ? { localId: folder.repository.localId }
+          : undefined,
+        workingCopy: {
+          id: folder.id,
+          repositoryId: folder.repository?.localId,
+          kind: "temporary",
+          name: folder.name,
+          branch: folder.repository?.branch,
+          commit: folder.repository?.commit,
+          deviceId: "agent-native-desktop",
+        },
+      },
+      dryRun: false,
+    } as never,
+  );
+  if (!connection.sourceId) return null;
+  await rememberLiveLocalFolderSource(
+    folder,
+    connection.sourceId,
+    connection.filesDatabaseId,
+  );
+  return connection.sourceId;
+}
+
+export async function syncLiveLocalFolder(folderId: string) {
+  let sourceId = liveLocalFolderSourceId(folderId);
+  if (!sourceId) {
+    const folderResult = await getDesktopContentFiles()?.getFolder({
+      folderId,
+    });
+    if (folderResult?.ok && folderResult.folder.contentSource?.sourceId) {
+      sourceId = folderResult.folder.contentSource.sourceId;
+      await rememberLiveLocalFolderSource(
+        folderResult.folder,
+        sourceId,
+        folderResult.folder.contentSource.databaseId,
+      );
+    }
+  }
+  if (!sourceId) return { synced: false as const, reason: "unregistered" };
+
+  const desktop = getDesktopContentFiles();
+  if (!desktop) return { synced: false as const, reason: "unavailable" };
+  const read = await desktop.readFiles({ folderId });
+  if (!read.ok) throw new Error(read.error);
+  const result = await callAction(
+    "sync-local-folder-source" as never,
+    {
+      sourceId,
+      files: read.sources ?? {},
+      fileIdentities: read.identities,
+      observedRevisions: read.revisions,
+      dryRun: false,
+    } as never,
+  );
+  return { synced: true as const, result };
+}

package/corpus/templates/content/app/root.tsx

@@ -68,6 +68,7 @@ import { Toaster } from "@/components/ui/toaster";
 import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
 
 import changelog from "../CHANGELOG.md?raw";
+import { LocalFolderLiveSync } from "./components/LocalFolderLiveSync";
 import { useDbSync } from "./hooks/use-db-sync";
 import { useNavigationState } from "./hooks/use-navigation-state";
 import { i18nCatalog } from "./i18n";
@@ -236,7 +237,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 function AppSetup() {
   useDbSync();
   useNavigationState();
-  return null;
+  return <LocalFolderLiveSync />;
 }
 
 function ThemeToggleItem() {