@agent-native/core 0.4.1 → 0.4.2

package/dist/adapters/sync/create-file-sync.js

@@ -0,0 +1,218 @@
+import fs from "fs";
+import path from "path";
+import { FileSync } from "./file-sync.js";
+import { validateIdentifier } from "./config.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isValidBackend(value) {
+    return (value === "drizzle" ||
+        value === "firestore" ||
+        value === "supabase" ||
+        value === "convex");
+}
+function requireEnv(key) {
+    const value = process.env[key];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+}
+function readPackageName() {
+    try {
+        const pkgPath = path.resolve(process.cwd(), "package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        return typeof pkg.name === "string" ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+async function createAdapter(backend, options) {
+    switch (backend) {
+        case "drizzle": {
+            try {
+                const { DrizzleFileSyncAdapter } = await import("../drizzle/adapter.js");
+                const dbPath = path.resolve(options.contentRoot, "sync.db");
+                return new DrizzleFileSyncAdapter(dbPath);
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+                console.error(`[file-sync] Failed to initialize Drizzle/SQLite adapter: ${safeMsg}`);
+                return null;
+            }
+        }
+        case "firestore": {
+            try {
+                requireEnv("GOOGLE_APPLICATION_CREDENTIALS");
+                const { FirestoreFileSyncAdapter } = await import("../firestore/adapter.js");
+                // Dynamic import of firebase-admin — only loads if installed
+                const adminModule = await import("firebase-admin");
+                // ESM dynamic import wraps CJS modules — unwrap .default if present
+                const admin = adminModule.default ?? adminModule;
+                const app = (admin.apps?.length ?? 0) > 0
+                    ? admin.apps[0]
+                    : admin.initializeApp({
+                        credential: admin.credential.applicationDefault(),
+                    });
+                const db = app.firestore();
+                return new FirestoreFileSyncAdapter(() => db.collection("files"));
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    "code" in err &&
+                    err.code === "ERR_MODULE_NOT_FOUND") {
+                    console.error("[file-sync] firebase-admin not installed. Run: pnpm add firebase-admin");
+                }
+                else if (err instanceof Error &&
+                    err.message.startsWith("Missing required")) {
+                    console.error(`[file-sync] ${err.message}`);
+                }
+                else {
+                    const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+                    console.error(`[file-sync] Failed to initialize Firestore: ${safeMsg}`);
+                }
+                return null;
+            }
+        }
+        case "supabase": {
+            try {
+                const url = requireEnv("SUPABASE_URL");
+                // Support new key name (SUPABASE_PUBLISHABLE_KEY) and legacy (SUPABASE_ANON_KEY)
+                const key = process.env.SUPABASE_PUBLISHABLE_KEY || process.env.SUPABASE_ANON_KEY;
+                if (!key) {
+                    throw new Error("Missing required environment variable: SUPABASE_PUBLISHABLE_KEY (or legacy SUPABASE_ANON_KEY)");
+                }
+                const { SupabaseFileSyncAdapter } = await import("../supabase/adapter.js");
+                const supabase = await import("@supabase/supabase-js");
+                // The adapter uses a duck-typed SupabaseClient interface to avoid hard deps.
+                // The real createClient returns a compatible but differently-typed object.
+                const client = supabase.createClient(url, key);
+                return new SupabaseFileSyncAdapter(client);
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    "code" in err &&
+                    err.code === "ERR_MODULE_NOT_FOUND") {
+                    console.error("[file-sync] @supabase/supabase-js not installed. Run: pnpm add @supabase/supabase-js");
+                }
+                else if (err instanceof Error &&
+                    err.message.startsWith("Missing required")) {
+                    console.error(`[file-sync] ${err.message}`);
+                }
+                else {
+                    const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+                    console.error(`[file-sync] Failed to initialize Supabase: ${safeMsg}`);
+                }
+                return null;
+            }
+        }
+        case "convex": {
+            try {
+                const url = requireEnv("CONVEX_URL");
+                if (!url.startsWith("https://")) {
+                    console.error("[file-sync] CONVEX_URL must use HTTPS");
+                    return null;
+                }
+                const { ConvexFileSyncAdapter } = await import("../convex/adapter.js");
+                const { ConvexClient } = await import("convex/browser");
+                const client = new ConvexClient(url);
+                return new ConvexFileSyncAdapter(client);
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    "code" in err &&
+                    err.code === "ERR_MODULE_NOT_FOUND") {
+                    console.error("[file-sync] convex not installed. Run: pnpm add convex");
+                }
+                else if (err instanceof Error &&
+                    err.message.startsWith("Missing required")) {
+                    console.error(`[file-sync] ${err.message}`);
+                }
+                else {
+                    const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+                    console.error(`[file-sync] Failed to initialize Convex: ${safeMsg}`);
+                }
+                return null;
+            }
+        }
+        default: {
+            const _exhaustive = backend;
+            console.error(`[file-sync] Unknown backend: ${String(_exhaustive)}`);
+            return null;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a file sync instance from environment variables.
+ *
+ * Returns a bundled result with the sync instance, SSE emitter, and shutdown
+ * function. Returns `{ status: "disabled" }` when `FILE_SYNC_ENABLED` is not
+ * `"true"`, and `{ status: "error", reason }` on misconfiguration.
+ *
+ * This is the first async `create*` function in the codebase — all others
+ * (createServer, createFileWatcher, createSSEHandler) are synchronous.
+ * Async is unavoidable here due to dynamic imports and adapter initialization.
+ */
+export async function createFileSync(options) {
+    if (process.env.FILE_SYNC_ENABLED !== "true") {
+        return { status: "disabled" };
+    }
+    // Default to "drizzle" (SQLite, zero-config) when FILE_SYNC_BACKEND is not set.
+    const backendEnv = process.env.FILE_SYNC_BACKEND || "drizzle";
+    if (!isValidBackend(backendEnv)) {
+        const reason = `FILE_SYNC_ENABLED=true but FILE_SYNC_BACKEND is invalid ("${backendEnv}")`;
+        console.warn(`[file-sync] ${reason}`);
+        return { status: "error", reason };
+    }
+    const backend = backendEnv;
+    const adapter = await createAdapter(backend, options);
+    if (!adapter) {
+        return {
+            status: "error",
+            reason: `Failed to initialize ${backend} adapter`,
+        };
+    }
+    let appId = readPackageName() || "app";
+    // Strip @scope/ prefix from scoped npm packages
+    appId = appId.replace(/^@[^/]+\//, "");
+    const ownerId = "shared";
+    try {
+        validateIdentifier("appId", appId);
+        validateIdentifier("ownerId", ownerId);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+        console.error(`[file-sync] Invalid identifier: ${safeMsg}`);
+        return { status: "error", reason: `Invalid identifier: ${safeMsg}` };
+    }
+    const syncOptions = {
+        appId,
+        ownerId,
+        contentRoot: options.contentRoot,
+        syncConfigPath: path.resolve(options.contentRoot, "sync-config.json"),
+        adapter,
+    };
+    const sync = new FileSync(syncOptions);
+    try {
+        await sync.initFileSync();
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.message.slice(0, 200) : "Unknown error";
+        console.error(`[file-sync] Init failed: ${safeMsg}`);
+        return { status: "error", reason: `Init failed: ${safeMsg}` };
+    }
+    return {
+        status: "ready",
+        fileSync: sync,
+        sseEmitter: { emitter: sync.syncEvents, event: "sync" },
+        shutdown: () => sync.stop(),
+    };
+}
+//# sourceMappingURL=create-file-sync.js.map

package/dist/adapters/sync/create-file-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-file-sync.js","sourceRoot":"","sources":["../../../src/adapters/sync/create-file-sync.ts"],"names":[],"mappings":"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"}

package/dist/adapters/sync/file-sync.d.ts

@@ -1,5 +1,4 @@
-import { EventEmitter } from "events";
-import type { FileSyncAdapter } from "./types.js";
+import { TypedEventEmitter, type FileSyncAdapter, type FileSyncEvents } from "./types.js";
 export interface FileSyncOptions {
     /** Unique app identifier (e.g. "content-workspace") */
     appId: string;
@@ -7,10 +6,12 @@ export interface FileSyncOptions {
     ownerId: string;
     /** Root directory for synced content */
     contentRoot: string;
-    /** Database adapter for file sync operations */
+    /** Adapter for file sync operations */
     adapter: FileSyncAdapter;
     /** Path to sync-config.json. Default: <contentRoot>/sync-config.json */
     syncConfigPath?: string;
+    /** Concurrency limit for startup sync operations. Default: 10 */
+    startupConcurrency?: number;
 }
 export type SyncEvent = {
     type: "conflict-resolved";
@@ -28,13 +29,26 @@ export type SyncEvent = {
 };
 export declare class FileSync {
     private options;
-    private recentlyPulled;
+    private lastSyncedHash;
+    private mergeBaseCache;
     private recentlyPushed;
-    private lastSyncedContent;
+    private expectedWrites;
+    private pushInFlight;
     private sharedSyncInitialized;
     private privateSyncInitialized;
+    private retryQueue;
+    private retryTimer;
+    private flushing;
+    private abortController;
+    private stopped;
+    private watchers;
+    private unsubscribeRemote;
     private purgeTimer;
-    readonly syncEvents: EventEmitter<[never]>;
+    private hasError;
+    private lastSyncTimestamp;
+    private conflictPaths;
+    readonly syncEvents: TypedEventEmitter<FileSyncEvents>;
+    get conflictCount(): number;
     constructor(options: FileSyncOptions);
     /**
      * Initialize the shared sync channel.
@@ -45,6 +59,20 @@ export declare class FileSync {
      * Initialize the private sync channel using a per-user UID.
      */
     initPrivateSync(userUid: string): Promise<void>;
+    /**
+     * Graceful shutdown. Cancels in-flight operations, drains retry queue,
+     * closes watchers, unsubscribes listeners, and disposes the adapter.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if a file was recently written by the sync engine (echo suppression).
+     * Consumes the entry — can only return true once per write.
+     */
+    wasSyncPulled(relPath: string): boolean;
+    /**
+     * Get paths of currently unresolved conflicts.
+     */
+    getConflictPaths(): string[];
     private emitSyncEvent;
     private markRecent;
     private wasRecent;
@@ -52,6 +80,12 @@ export declare class FileSync {
     private readLocalFile;
     private writeSyncedFile;
     private docId;
+    private updateMergeBase;
+    private enqueueRetry;
+    private flushRetryQueue;
+    private appendDeadLetter;
+    private writeDeadLetterLog;
+    private writeSyncStatus;
     private resolveConflict;
     private initStartupSync;
     private startRemoteListener;

package/dist/adapters/sync/file-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-sync.d.ts","sourceRoot":"","sources":["../../../src/adapters/sync/file-sync.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GACjB;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;CACvD,GACD;IACE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAQnE,qBAAa,QAAQ;IAUP,OAAO,CAAC,OAAO;IAT3B,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,UAAU,CAA+C;IAEjE,QAAQ,CAAC,UAAU,wBAAsB;gBAErB,OAAO,EAAE,eAAe;IAI5C;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBnC;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrD,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,eAAe;YAiET,eAAe;IAmF7B,OAAO,CAAC,mBAAmB;IAgE3B,OAAO,CAAC,gBAAgB;CAyEzB"}
+{"version":3,"file":"file-sync.d.ts","sourceRoot":"","sources":["../../../src/adapters/sync/file-sync.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EAGpB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,eAAe,CAAC;IACzB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GACjB;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;CACvD,GACD;IACE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAWnE,qBAAa,QAAQ;IAqCP,OAAO,CAAC,OAAO;IAnC3B,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,sBAAsB,CAAS;IAGvC,OAAO,CAAC,UAAU,CAGd;IACJ,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,UAAU,CAA+C;IAGjE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,aAAa,CAAqB;IAG1C,QAAQ,CAAC,UAAU,oCAA2C;IAE9D,IAAI,aAAa,IAAI,MAAM,CAE1B;gBAEmB,OAAO,EAAE,eAAe;IAQ5C;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAmDnC;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD3B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQvC;;OAEG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAM5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,YAAY;YAuBN,eAAe;IA6B7B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,eAAe;YAuFT,eAAe;IA4I7B,OAAO,CAAC,mBAAmB;IAkG3B,OAAO,CAAC,gBAAgB;CA6FzB"}