@sleekcms/sync 1.4.3 → 1.5.0

package/README.md

@@ -48,12 +48,15 @@ sleekcms --token <YOUR_AUTH_TOKEN>
 ## Usage
 
 ```bash
-# Basic
+# Basic — auto-sync on every save
 npx @sleekcms/sync --token abc123-xxxx
 
+# Manual sync — push changes only when you press [s]
+npx @sleekcms/sync --token abc123-xxxx --manual
+
 ```
 
-Once running, press `r` to re-fetch all files or `x` / `Ctrl+C` to exit.
+Once running, press `r` to re-fetch all files or `x` / `Ctrl+C` to exit. In `--manual` mode, press `s` to push your changes on demand.
 
 ---
 
@@ -136,12 +139,24 @@ On first run, the CLI pulls the full site state from the server. After that, a l
 Your editor → file save → watcher → SleekCMS API → rebuild → live site
 ```
 
-### Watch mode commands
+### Manual sync mode (`--manual`)
+
+Pass `--manual` (`-m`) to skip the live watcher. The CLI still does the initial fetch, but after that nothing is pushed until you press `s`. On each `s`, it scans the workspace, diffs against the cached state in `.cache/`, and pushes only the files that changed since your last fetch or sync — the same diff logic, run on demand instead of on every save.
+
+This is useful when you want to batch a set of edits (or let an AI agent finish writing several files) and push them as one deliberate action.
+
+```
+Your editor → edit freely → press [s] → diff vs last fetch → SleekCMS API → live site
+```
+
+### Session commands
 
 | Key | Action |
 |---|---|
+| `s` | Push changed files now (`--manual` mode only) |
 | `r` | Re-fetch all files from server |
 | `x` or `Ctrl+C` | Exit and clean up local workspace |
+| `q` | Quit, keeping local files |
 
 ---
 

package/dist/AGENT.md

@@ -732,4 +732,4 @@ Template:
 17. Always create RSS feed for blogs and link them in meta so it is discoverable. Use "rss.xml" as the key.
 18. Make the sites extremely SEO friendly and sharing friendly.
 19. When naming files for models, use - (dash) as word separator. Don't use _ (underscore) as it is mapped to / (slash) in path
-
+20. Not all content details need to be modeled. If there is content which is not meant to be updated, such as button labels, links etc. you can inline that in the EJS view instead of adding fields to model and using from there. Decide what is relevant.

package/dist/cli.d.ts

@@ -6,13 +6,16 @@ export interface CliOptions {
     token?: string;
     env?: string;
     path?: string;
+    manual?: boolean;
 }
 export interface KeyboardHandlers {
     onExit?: () => void | Promise<unknown>;
+    onQuit?: () => void | Promise<unknown>;
     onRefetch?: () => void | Promise<unknown>;
+    onSync?: () => void | Promise<unknown>;
 }
 export declare function parseArgs(): CliOptions;
 export declare function prompt(question: string): Promise<string>;
-export declare function showWatchHelp(): void;
-export declare function setupKeyboardInput(handlers: KeyboardHandlers): void;
-export declare function showEditorMenu(viewsDir: string, handlers: KeyboardHandlers): void;
+export declare function showWatchHelp(manual?: boolean): void;
+export declare function setupKeyboardInput(handlers: KeyboardHandlers, manual?: boolean): void;
+export declare function showEditorMenu(viewsDir: string, handlers: KeyboardHandlers, manual?: boolean): void;

package/dist/cli.js

@@ -23,11 +23,13 @@ function parseArgs() {
         .option("-t, --token <token>", "API authentication token (required)")
         .addOption(new commander_1.Option("-e, --env <env>", "Environment (localhost, development, production)").default("production").hideHelp())
         .option("-p, --path <path>", "Directory path for files (default: <token-prefix>-views)")
+        .option("-m, --manual", "Manual sync mode: don't auto-sync on file changes; press [s] to push diffs on demand")
         .addHelpText("after", `
 Examples:
   $ cms-sync --token abc123-xxxx
   $ cms-sync -t abc123-xxxx -e development
   $ cms-sync -t abc123-xxxx -p ./my-templates
+  $ cms-sync -t abc123-xxxx -m            # manual sync — push only when you press [s]
 `)
         .parse(process.argv);
     return commander_1.program.opts();
@@ -66,10 +68,11 @@ function commandExists(cmd) {
         return false;
     }
 }
-function showWatchHelp() {
-    console.log("📋 Commands: [r] Re-fetch all files  [x] Exit\n");
+function showWatchHelp(manual = false) {
+    const sync = manual ? "[s] Sync changes  " : "";
+    console.log(`📋 Commands: ${sync}[r] Re-fetch all files  [x] Exit (cleanup)  [q] Quit (keep files)\n`);
 }
-function setupKeyboardInput(handlers) {
+function setupKeyboardInput(handlers, manual = false) {
     if (process.stdin.isTTY) {
         process.stdin.setRawMode(true);
         rawModeEnabled = true;
@@ -84,41 +87,55 @@ function setupKeyboardInput(handlers) {
             return;
         }
         const cmd = key.toLowerCase();
-        if (cmd === "r" && handlers.onRefetch) {
+        if (cmd === "s" && handlers.onSync) {
+            await handlers.onSync();
+            showWatchHelp(manual);
+        }
+        else if (cmd === "r" && handlers.onRefetch) {
             console.log("\n🔄 Re-fetching all files...");
             await handlers.onRefetch();
-            console.log("👀 Watching for changes...");
-            showWatchHelp();
+            if (!manual)
+                console.log("👀 Watching for changes...");
+            showWatchHelp(manual);
         }
         else if (cmd === "x" && handlers.onExit) {
             await handlers.onExit();
         }
+        else if (cmd === "q" && handlers.onQuit) {
+            await handlers.onQuit();
+        }
     });
 }
 const EDITOR_CANDIDATES = [
     { name: "VS Code", cmd: "code", args: (dir) => ["-n", dir] },
     { name: "Cursor", cmd: "cursor", args: (dir) => ["-n", dir] },
 ];
-function showEditorMenu(viewsDir, handlers) {
+function statusLine(manual, suffix = "") {
+    const base = manual ? "✋ Manual sync mode — press [s] to push changes." : "👀 Watching for changes...";
+    console.log(`${base}${suffix}`);
+}
+function showEditorMenu(viewsDir, handlers, manual = false) {
     const editors = EDITOR_CANDIDATES
         .filter(e => commandExists(e.cmd))
         .map((e, i) => ({ ...e, key: String(i + 1) }));
     if (editors.length === 0) {
-        console.log("\n👀 Watching for changes...");
-        showWatchHelp();
-        setupKeyboardInput(handlers);
+        console.log("");
+        statusLine(manual);
+        showWatchHelp(manual);
+        setupKeyboardInput(handlers, manual);
         return;
     }
     console.log("\n📂 Open in editor:");
     editors.forEach(e => console.log(`   [${e.key}] ${e.name}`));
     console.log("   [Enter] Skip");
-    console.log("   [x] Quit\n");
+    console.log("   [x] Exit (cleanup)");
+    console.log("   [q] Quit (keep files)\n");
     const rl = readline_1.default.createInterface({
         input: process.stdin,
         output: process.stdout,
     });
-    // Count lines to clear (menu header + editors + skip + quit + empty + prompt)
-    const linesToClear = editors.length + 5;
+    // Count lines to clear (menu header + editors + skip + exit + quit + empty + prompt)
+    const linesToClear = editors.length + 6;
     rl.question("Select editor: ", async (answer) => {
         rl.close();
         // Clear the menu lines
@@ -127,14 +144,20 @@ function showEditorMenu(viewsDir, handlers) {
             process.stdout.write("\x1b[2K\n"); // Clear each line
         }
         process.stdout.write(`\x1b[${linesToClear}A`); // Move back up
-        if (answer.trim().toLowerCase() === "x") {
+        const choice = answer.trim().toLowerCase();
+        if (choice === "x") {
             if (handlers.onExit)
                 await handlers.onExit();
             return;
         }
+        if (choice === "q") {
+            if (handlers.onQuit)
+                await handlers.onQuit();
+            return;
+        }
         const selected = editors.find(e => e.key === answer.trim());
         if (selected) {
-            console.log(`👀 Watching for changes... (opened ${selected.name})`);
+            statusLine(manual, ` (opened ${selected.name})`);
             (0, child_process_1.spawn)(selected.cmd, selected.args(viewsDir), {
                 detached: true,
                 stdio: "ignore",
@@ -142,9 +165,9 @@ function showEditorMenu(viewsDir, handlers) {
             }).unref();
         }
         else {
-            console.log("👀 Watching for changes...");
+            statusLine(manual);
         }
-        showWatchHelp();
-        setupKeyboardInput(handlers);
+        showWatchHelp(manual);
+        setupKeyboardInput(handlers, manual);
     });
 }

package/dist/index.js

@@ -116,6 +116,32 @@ async function handleExit() {
     await cleanupFiles(VIEWS_DIR);
     process.exit(0);
 }
+async function handleQuit() {
+    if (isShuttingDown)
+        return;
+    isShuttingDown = true;
+    watcher.setShuttingDown(true);
+    console.log("\n⚠️ Quitting (keeping files)...");
+    await watcher.stopWatching();
+    if (VIEWS_DIR)
+        console.log(`📁 Workspace left at: ${VIEWS_DIR}`);
+    process.exit(0);
+}
+/**
+ * Manual sync trigger ([s] key). Scans the workspace on demand, diffs against
+ * the cached state in .cache/state.json, and pushes only changed files.
+ */
+async function handleManualSync() {
+    console.log("\n🔄 Syncing changes...");
+    try {
+        const { pushed } = await runSync();
+        console.log(pushed > 0 ? `✅ Synced ${pushed} change(s).` : "✔️ No changes to sync.");
+    }
+    catch (err) {
+        const e = err;
+        console.error("❌ Sync failed:", e.body || e.message);
+    }
+}
 async function main() {
     await initConfig();
     try {
@@ -126,17 +152,24 @@ async function main() {
         console.error("❌ Sync failed:", e.body || e.message);
         process.exit(1);
     }
-    watcher.init({ viewsDir: VIEWS_DIR, onSync: runSync, onIdle: handleExit });
-    watcher.monitorFiles();
+    const manual = options.manual ?? false;
+    if (!manual) {
+        watcher.init({ viewsDir: VIEWS_DIR, onSync: runSync, onIdle: handleExit });
+        watcher.monitorFiles();
+    }
     console.log(`\n✅ Ready! Editing session started for site - ${site.name}.`);
     console.log(`\n📁 Workspace created at: ${VIEWS_DIR}`);
     if (ENV !== "production")
         console.log(`🌐 Environment: ${ENV}`);
+    if (manual)
+        console.log(`\n✋ Manual sync mode — changes are pushed only when you press [s].`);
     console.log(`\n⚠️  Files will be cleaned up on exit (Ctrl+C).`);
     cli.showEditorMenu(VIEWS_DIR, {
         onExit: handleExit,
+        onQuit: handleQuit,
         onRefetch: () => runSync({ flush: true }),
-    });
+        ...(manual ? { onSync: handleManualSync } : {}),
+    }, manual);
     process.on("SIGINT", async () => {
         console.log("\n🛑 Caught interrupt signal (Ctrl+C)");
         await handleExit();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sleekcms/sync",
-    "version": "1.4.3",
+    "version": "1.5.0",
     "description": "Edit SleekCMS sites locally — models, content, templates, images — with live two-way sync and AI agent support.",
     "keywords": [
         "sleekcms",