@sleekcms/sync 1.4.4 → 1.6.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 |
 
 ---
 
@@ -266,7 +281,7 @@ Models describe the shape of your content. They're JSON-like files with unquoted
 | `json` | Object or array |
 | `block(key)` | Embedded block object |
 | `stack` | Array of heterogeneous block objects; each item carries `_block: "<block_key>"` to name its block |
-| `entry(key)` | Entry object or slug reference |
+| `entry(key)` | Reference token `"<index>\|<text>"` — `index` is the entry's 0-based position in `content/entries/<key>+.json` (what binds); the optional `<text>` is the entry's opening content copied verbatim (a substring check, not a summary you write). Resolves to the entry object in templates |
 
 ---
 

package/dist/AGENT.md

@@ -279,7 +279,7 @@ Model fields declare both the editor type and the shape expected in content JSON
 | `block(key)` | Object matching that block's model; stored inline in the parent page/entry content and rendered with `blocks/<key>.ejs` |
 | `[block(key)]` | Array of block objects; each item matches the block model and renders with `blocks/<key>.ejs` |
 | `stack` | Array of heterogeneous block-shaped objects. Each item is `{ "_block": "<block_key>", ...fields_of_that_block }`. `_block` is the target block's key as a plain string; the remaining keys must match that block's model. Different items in the same stack may use different blocks. Stored inline; each item renders through its own `blocks/<key>.ejs`. The CMS resolves block keys to ids server-side — never write numeric ids. |
-| `entry(key)` / `[entry(key)]` | Slug string / array of slug strings in content JSON; entry object / array of entry objects in templates |
+| `entry(key)` / `[entry(key)]` | Reference token `"<index>\|<text>"` (or an array of them) in content JSON; entry object / array of entry objects in templates. `index` is the 0-based position of the target entry in its `content/entries/<key>+.json` list — that is what binds. `\|<text>` is optional: the **opening characters of that entry's content, copied verbatim** (matched as a substring — not a description you compose), used only to relocate the entry if the list shifted. You may write just the index (`"2"` or `2`). |
 | Group `{ ... }` | Nested object |
 | Collection `[{ ... }]` | Array of nested objects |
 
@@ -324,11 +324,11 @@ The content file at `content/pages/about.json`:
         "cta_label": "Contact us",
         "cta_link": "/contact"
     },
-    "tags": ["engineering", "design"]
+    "tags": ["0|Engineering", "2|Design"]
 }
 ```
 
-Here `hero` is embedded block data stored directly in the page content file. `image` and `hero.background` use the shortcut form — on save, the sync engine replaces each shortcut with a real image object (`{ "url": "...", "alt": "..." }`). Write the object form directly when you have a specific asset URL.
+Here `hero` is embedded block data stored directly in the page content file. `image` and `hero.background` use the shortcut form — on save, the sync engine replaces each shortcut with a real image object (`{ "url": "...", "alt": "..." }`). Write the object form directly when you have a specific asset URL. `tags` references entries by position — `"0|Engineering"` points at the first entry in `content/entries/tags+.json`, where `Engineering` is just the start of that entry's content copied verbatim (a substring check, not a description you write). The index is what binds on save; the text only helps relocate the entry if the list shifted, and a bare index (`"0"`) is also accepted.
 
 ### Markdown content files
 

package/dist/cli.d.ts

@@ -6,14 +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 (cleanup)  [q] Quit (keep files)\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,11 +87,16 @@ 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();
@@ -102,14 +110,19 @@ 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:");
@@ -144,7 +157,7 @@ function showEditorMenu(viewsDir, handlers) {
         }
         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",
@@ -152,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

@@ -127,6 +127,21 @@ async function handleQuit() {
         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 {
@@ -137,18 +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.4",
+    "version": "1.6.0",
     "description": "Edit SleekCMS sites locally — models, content, templates, images — with live two-way sync and AI agent support.",
     "keywords": [
         "sleekcms",