@gobi-ai/cli 0.6.14 → 0.6.15

package/dist/commands/sync.js

@@ -343,8 +343,12 @@ function matchesPaths(filePath, paths) {
 async function performSync(baseUrl, vaultSlug, state, syncfilesChanges, privatefilesChanges, localFiles, opts, token) {
     const body = {
         cursor: state.cursor,
-        // dryRun: don't mutate server-side syncfiles/privatefiles
-        syncfilesChanges: opts.dryRun ? { added: [], removed: [] } : syncfilesChanges,
+        // dryRun: suppress removes (destructive) but send adds so the server can
+        // compute the correct file scope for the preview. Privatefiles are fully
+        // suppressed — they don't affect file actions and should never mutate in dry-run.
+        syncfilesChanges: opts.dryRun
+            ? { added: syncfilesChanges.added, removed: [] }
+            : syncfilesChanges,
         privatefilesChanges: opts.dryRun ? { added: [], removed: [] } : privatefilesChanges,
         clientFiles: localFiles,
         uploadOnly: opts.uploadOnly,
@@ -357,6 +361,10 @@ export async function runSync(opts) {
     const baseUrl = opts.webdriveUrl ?? WEBDRIVE_BASE_URL;
     const gobiDir = join(vaultDir, ".gobi");
     mkdirSync(gobiDir, { recursive: true });
+    const token = opts.authToken ?? (await getValidToken());
+    if (opts.execute) {
+        return executeSyncPlan(opts, baseUrl, token, gobiDir);
+    }
     const state = loadSyncState(gobiDir);
     // --full: treat this run as a first-time sync (re-check every file against the server)
     if (opts.full) {
@@ -365,7 +373,6 @@ export async function runSync(opts) {
         if (!jsonMode)
             console.log("Full sync: ignoring cursor and hash cache.");
     }
-    const token = opts.authToken ?? (await getValidToken());
     // Read syncfiles whitelist
     const syncfilesExistsLocally = existsSync(join(gobiDir, "syncfiles"));
     const { patterns: currPatterns, contentHash: currSyncfilesHash } = readSyncfiles(gobiDir);
@@ -474,6 +481,26 @@ export async function runSync(opts) {
     }
     if (!jsonMode)
         console.log(` ${syncResp.files.length} action(s).`);
+    // Write plan file if requested (dry-run + --plan-file)
+    if (opts.dryRun && opts.planFile) {
+        const offlineDeletions = Object.keys(state.hashCache).filter((p) => !localPathSet.has(p) && !existsSync(join(vaultDir, p)));
+        const plan = {
+            vaultSlug,
+            syncCursor: syncResp.cursor,
+            syncfilesHash: syncResp.syncfilesHash || null,
+            privatefilesHash: syncResp.privatefilesHash || null,
+            downloadSyncfiles: !!(syncResp.syncfilesHash &&
+                (syncResp.syncfilesHash !== state.syncfilesHash || !syncfilesExistsLocally)),
+            downloadPrivatefiles: !!(syncResp.privatefilesHash &&
+                (syncResp.privatefilesHash !== state.privatefilesHash || !privatefilesExistsLocally)),
+            actions: syncResp.files.filter((f) => matchesPaths(f.path, opts.paths ?? [])),
+            offlineDeletions,
+            createdAt: new Date().toISOString(),
+        };
+        await writeFile(opts.planFile, JSON.stringify(plan, null, 2));
+        if (!jsonMode)
+            console.log(`Plan written to ${opts.planFile}`);
+    }
     // Process actions
     let uploaded = 0, downloaded = 0, deletedLocally = 0, conflicts = 0, skipped = 0, errors = 0;
     const errorDetails = [];
@@ -633,15 +660,17 @@ export async function runSync(opts) {
     }
     // Persist state (always, even on partial failures)
     const finalCursor = Math.max(syncResp.cursor, maxMutationCursor !== null ? maxMutationCursor : 0);
-    state.cursor = finalCursor;
-    state.syncfilesHash = syncResp.syncfilesHash || currSyncfilesHash;
-    // If the server returned an empty syncfilesHash the vault was deleted server-side
-    // (empty patterns path). Reset patterns so the next sync re-registers them as "added",
-    // which lets the 409 retry resurrect the vault.
-    state.patterns = syncResp.syncfilesHash === "" ? [] : effectivePatterns;
-    state.privatePatterns = effectivePrivatePatterns;
-    state.privatefilesHash = syncResp.privatefilesHash || state.privatefilesHash;
-    saveSyncState(gobiDir, state);
+    if (!opts.dryRun) {
+        state.cursor = finalCursor;
+        state.syncfilesHash = syncResp.syncfilesHash || currSyncfilesHash;
+        // If the server returned an empty syncfilesHash the vault was deleted server-side
+        // (empty patterns path). Reset patterns so the next sync re-registers them as "added",
+        // which lets the 409 retry resurrect the vault.
+        state.patterns = syncResp.syncfilesHash === "" ? [] : effectivePatterns;
+        state.privatePatterns = effectivePrivatePatterns;
+        state.privatefilesHash = syncResp.privatefilesHash || state.privatefilesHash;
+        saveSyncState(gobiDir, state);
+    }
     // Output summary
     const result = {
         uploaded,
@@ -672,6 +701,184 @@ export async function runSync(opts) {
             process.exitCode = 1;
         }
     }
+    return result;
+}
+// ─── Execute Plan ─────────────────────────────────────────────────────────────
+async function executeSyncPlan(opts, baseUrl, token, gobiDir) {
+    const { vaultSlug, dir: vaultDir, jsonMode } = opts;
+    if (!opts.planFile)
+        throw new GobiError("--execute requires --plan-file", "INVALID_OPTION");
+    if (!existsSync(opts.planFile))
+        throw new GobiError(`Plan file not found: ${opts.planFile}`, "PLAN_NOT_FOUND");
+    const plan = JSON.parse(readFileSync(opts.planFile, "utf-8"));
+    if (plan.vaultSlug !== vaultSlug)
+        throw new GobiError(`Plan is for vault "${plan.vaultSlug}", not "${vaultSlug}"`, "PLAN_MISMATCH");
+    // Validate conflict coverage upfront
+    const conflictActions = plan.actions.filter((a) => a.action === "conflict");
+    const canFallback = opts.conflict && opts.conflict !== "ask";
+    const unresolvedConflicts = conflictActions
+        .filter((a) => !opts.conflictChoices?.[a.path])
+        .map((a) => a.path);
+    if (unresolvedConflicts.length > 0 && !canFallback) {
+        throw new GobiError(`Unresolved conflicts — pass --conflict or add to --conflict-choices:\n${unresolvedConflicts.map((p) => `  ${p}`).join("\n")}`, "UNRESOLVED_CONFLICTS");
+    }
+    const state = loadSyncState(gobiDir);
+    // Execute offline deletions
+    let maxMutationCursor = null;
+    for (const path of plan.offlineDeletions) {
+        if (opts.downloadOnly)
+            continue;
+        if (!jsonMode)
+            console.log(`  Deleting remote (offline deletion): ${path}`);
+        try {
+            const cursor = await webdriveDelete(baseUrl, vaultSlug, path, token);
+            if (cursor !== null && (maxMutationCursor === null || cursor > maxMutationCursor))
+                maxMutationCursor = cursor;
+        }
+        catch (err) {
+            if (!jsonMode)
+                console.error(`  Error deleting remote ${path}: ${err.message}`);
+        }
+        delete state.hashCache[path];
+    }
+    // Execute actions from plan
+    let uploaded = 0, downloaded = 0, deletedLocally = 0, conflicts = 0, skipped = 0, errors = 0;
+    const errorDetails = [];
+    for (const entry of plan.actions) {
+        try {
+            const absPath = join(vaultDir, entry.path);
+            if (entry.action === "upload") {
+                if (opts.downloadOnly)
+                    continue;
+                const content = readFileSync(absPath);
+                const hash = md5Hex(content);
+                const cursor = await webdrivePut(baseUrl, vaultSlug, entry.path, content, hash, token);
+                if (cursor !== null && (maxMutationCursor === null || cursor > maxMutationCursor))
+                    maxMutationCursor = cursor;
+                state.hashCache[entry.path] = { hash, mtime: statSync(absPath).mtimeMs, size: content.length };
+                if (!jsonMode)
+                    console.log(`  Uploaded: ${entry.path}`);
+                uploaded++;
+            }
+            else if (entry.action === "download") {
+                if (opts.uploadOnly)
+                    continue;
+                const content = await webdriveGet(baseUrl, vaultSlug, entry.path, token);
+                mkdirSync(dirname(absPath), { recursive: true });
+                await writeFile(absPath, content);
+                const hash = md5Hex(content);
+                state.hashCache[entry.path] = { hash, mtime: statSync(absPath).mtimeMs, size: content.length };
+                if (!jsonMode)
+                    console.log(`  Downloaded: ${entry.path}`);
+                downloaded++;
+            }
+            else if (entry.action === "delete_local") {
+                if (opts.uploadOnly)
+                    continue;
+                if (!existsSync(absPath))
+                    continue;
+                await trash(absPath);
+                delete state.hashCache[entry.path];
+                if (!jsonMode)
+                    console.log(`  Deleted local (moved to trash): ${entry.path}`);
+                deletedLocally++;
+            }
+            else if (entry.action === "conflict") {
+                conflicts++;
+                const choice = opts.conflictChoices?.[entry.path] ?? opts.conflict ?? "skip";
+                if (choice === "server") {
+                    const content = await webdriveGet(baseUrl, vaultSlug, entry.path, token);
+                    mkdirSync(dirname(absPath), { recursive: true });
+                    await writeFile(absPath, content);
+                    const hash = md5Hex(content);
+                    state.hashCache[entry.path] = { hash, mtime: statSync(absPath).mtimeMs, size: content.length };
+                    if (!jsonMode)
+                        console.log(`  Conflict resolved (server): ${entry.path}`);
+                    downloaded++;
+                }
+                else if (choice === "client") {
+                    if (!jsonMode)
+                        console.log(`  Conflict resolved (local kept): ${entry.path}`);
+                }
+                else {
+                    skipped++;
+                    if (!jsonMode)
+                        console.log(`  Conflict skipped: ${entry.path}`);
+                }
+            }
+        }
+        catch (err) {
+            errors++;
+            const msg = err.message;
+            errorDetails.push({ path: entry.path, action: entry.action, error: msg });
+            if (!jsonMode)
+                console.error(`  Error [${entry.action}] ${entry.path}: ${msg}`);
+        }
+    }
+    // Download syncfiles/privatefiles as indicated by plan
+    const { patterns: currPatterns } = readSyncfiles(gobiDir);
+    let effectivePatterns = currPatterns;
+    if (plan.downloadSyncfiles) {
+        try {
+            const content = await webdriveGet(baseUrl, vaultSlug, ".gobi/syncfiles", token);
+            await writeFile(join(gobiDir, "syncfiles"), content);
+            effectivePatterns = readSyncfiles(gobiDir).patterns;
+            if (!jsonMode)
+                console.log("  Updated local syncfiles from server.");
+        }
+        catch (err) {
+            if (!jsonMode)
+                console.error(`Warning: Failed to download syncfiles: ${err.message}`);
+        }
+    }
+    let effectivePrivatePatterns = readPrivatefiles(gobiDir);
+    if (plan.downloadPrivatefiles) {
+        try {
+            const content = await webdriveGet(baseUrl, vaultSlug, ".gobi/privatefiles", token);
+            await writeFile(join(gobiDir, "privatefiles"), content);
+            effectivePrivatePatterns = readPrivatefiles(gobiDir);
+            if (!jsonMode)
+                console.log("  Updated local privatefiles from server.");
+        }
+        catch (err) {
+            if (!jsonMode)
+                console.error(`Warning: Failed to download privatefiles: ${err.message}`);
+        }
+    }
+    // Save state
+    const finalCursor = Math.max(plan.syncCursor, maxMutationCursor ?? 0);
+    state.cursor = finalCursor;
+    state.syncfilesHash = plan.syncfilesHash ?? state.syncfilesHash;
+    state.patterns = effectivePatterns;
+    state.privatePatterns = effectivePrivatePatterns;
+    state.privatefilesHash = plan.privatefilesHash ?? state.privatefilesHash;
+    saveSyncState(gobiDir, state);
+    // Delete plan file after successful execution
+    rmSync(opts.planFile, { force: true });
+    const result = {
+        uploaded,
+        downloaded,
+        deletedLocally,
+        conflicts,
+        skipped,
+        errors,
+        cursor: finalCursor,
+        errorDetails,
+    };
+    if (jsonMode) {
+        jsonOut(result);
+    }
+    else {
+        console.log("\nSync complete.");
+        console.log(`  Uploaded:      ${uploaded}`);
+        console.log(`  Downloaded:    ${downloaded}`);
+        console.log(`  Deleted local: ${deletedLocally}`);
+        console.log(`  Conflicts:     ${conflicts}`);
+        console.log(`  Errors:        ${errors}`);
+        if (errors > 0)
+            process.exitCode = 1;
+    }
+    return result;
 }
 // ─── Commander Registration ───────────────────────────────────────────────────
 export function registerSyncCommand(program) {
@@ -685,14 +892,29 @@ export function registerSyncCommand(program) {
         .option("--dry-run", "Preview changes without making them")
         .option("--full", "Full sync: ignore cursor and hash cache, re-check every file")
         .option("--path <path>", "Restrict sync to a specific file or folder (repeatable)", (v, prev) => prev.concat(v), [])
+        .option("--plan-file <path>", "Write dry-run plan to file (use with --dry-run) or read plan to execute (use with --execute)")
+        .option("--execute", "Execute a previously written plan file (requires --plan-file)")
+        .option("--conflict-choices <json>", "Per-file conflict resolutions as JSON object, e.g. '{\"file.md\":\"server\"}' (use with --execute)")
         .action(async function (opts) {
         if (opts.uploadOnly && opts.downloadOnly) {
             throw new GobiError("--upload-only and --download-only are mutually exclusive.", "INVALID_OPTION");
         }
+        if (opts.execute && !opts.planFile) {
+            throw new GobiError("--execute requires --plan-file", "INVALID_OPTION");
+        }
         const validStrategies = ["ask", "server", "client", "skip"];
         if (!validStrategies.includes(opts.conflict)) {
             throw new GobiError(`Invalid --conflict value "${opts.conflict}". Use: ask|server|client|skip`, "INVALID_OPTION");
         }
+        let conflictChoices;
+        if (opts.conflictChoices) {
+            try {
+                conflictChoices = JSON.parse(opts.conflictChoices);
+            }
+            catch {
+                throw new GobiError("--conflict-choices must be valid JSON", "INVALID_OPTION");
+            }
+        }
         const vaultSlug = getVaultSlug();
         const dir = opts.dir ? pathResolve(opts.dir) : process.cwd();
         await runSync({
@@ -704,6 +926,9 @@ export function registerSyncCommand(program) {
             dryRun: !!opts.dryRun,
             full: !!opts.full,
             paths: opts.path ?? [],
+            planFile: opts.planFile,
+            execute: !!opts.execute,
+            conflictChoices,
             jsonMode: isJsonMode(this),
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobi-ai/cli",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "description": "CLI client for the Gobi collaborative knowledge platform",
   "license": "MIT",
   "type": "module",

package/skills/gobi/SKILL.md

@@ -10,12 +10,12 @@ description: >-
 allowed-tools: Bash(gobi:*)
 metadata:
   author: gobi-ai
-  version: "0.6.13"
+  version: "0.6.14"
 ---
 
 # gobi-cli
 
-A CLI client for the Gobi collaborative knowledge platform (v0.6.13).
+A CLI client for the Gobi collaborative knowledge platform (v0.6.14).
 
 ## Prerequisites