@sleekcms/sync 1.2.3 → 1.4.0

package/README.md

@@ -2,13 +2,13 @@
 
 **Build complete websites with AI. Edit them locally. Deploy instantly.**
 
-The SleekCMS CLI brings your CMS to your code editor — with full AI-agent support baked in. Spin up an entirely new site by describing it in plain English, or drop into any existing site and edit templates, content, and styles the way you'd expect: locally, with real files, in your editor of choice.
+SleekCMS Sync brings your CMS to your code editor — with full AI-agent support baked in. Spin up an entirely new site by describing it in plain English, or drop into any existing site and edit templates, content, and styles the way you'd expect: locally, with real files, in your editor of choice.
 
 Every save auto-syncs. Every change goes live. No build steps. No Git hooks. No infrastructure to manage.
 
 ---
 
-## Why developers love it
+## How does it work
 
 - **AI generates your entire site from a description** — models, templates, layouts, styles, and content, all wired up and ready to go.
 - **AI-generated sites are plain files** — EJS templates, JSON content, CSS, JS. You own every line. Open in VS Code, Cursor, or any editor.
@@ -24,7 +24,7 @@ Every save auto-syncs. Every change goes live. No build steps. No Git hooks. No
 npx @sleekcms/sync --token <YOUR_AUTH_TOKEN>
 ```
 
-That's it. The CLI fetches your site, opens an editor prompt, and starts watching for changes. Grab a token from your [SleekCMS dashboard](https://app.sleekcms.com).
+That's it. The CLI fetches your site, opens an editor prompt, and starts watching for changes. Grab a token from your [SleekCMS > Builder](https://app.sleekcms.com).
 
 ---
 
@@ -47,24 +47,10 @@ sleekcms --token <YOUR_AUTH_TOKEN>
 
 ## Usage
 
-```bash
-npx @sleekcms/sync [OPTIONS]
-```
-
-| Option             | Alias | Description                                            | Default       |
-|--------------------|-------|--------------------------------------------------------|---------------|
-| `--token <token>`  | `-t`  | Your SleekCMS CLI auth token (required)                | —             |
-| `--path <path>`    | `-p`  | Parent directory for the local workspace               | `~/.sleekcms` |
-| `--help`           | `-h`  | Show help                                              | —             |
-
-> The actual workspace folder is created at `<path>/<site-name>-<site-id>/`.
-
 ```bash
 # Basic
 npx @sleekcms/sync --token abc123-xxxx
 
-# Custom workspace folder
-npx @sleekcms/sync -t abc123-xxxx -p ~/Sites
 ```
 
 Once running, press `r` to re-fetch all files or `x` / `Ctrl+C` to exit.
@@ -272,12 +258,14 @@ Models describe the shape of your content. They're JSON-like files with unquoted
 | `markdown` | Markdown string |
 | `number` | Number |
 | `boolean` | `true` / `false` |
+| `emoji` | Single Unicode emoji character, e.g. `"😀"` |
 | `date` | `YYYY-MM-DD` |
 | `image` | `{ url, alt }` |
 | `video` | `{ url, embed }` |
 | `link` | URL string |
 | `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 |
 
 ---

package/dist/AGENT.md

@@ -52,6 +52,7 @@ Examples:
 
 /content/pages/<key>.json          Content for a single (non-list) page
 /content/pages/<key>/<slug>.json   Content for one item of a collection page (<key> ends with +)
+/content/pages/<key>/<slug>.md     Same as above, but as Markdown with YAML frontmatter — used when the model qualifies (see "Markdown content files" below)
 /content/entries/<key>.json        Content for a single entry (object)
 /content/entries/<key+>.json       Content for a collection entry (array of objects; <key>+ matches the model filename)
 
@@ -188,6 +189,62 @@ Block models cannot contain other blocks. Use groups (`{ ... }`) or collections
 
 Repeatable blocks use the same collection syntax as groups and entries: `[block(cta)]`. Use this sparingly, only when each repeated item should use the same reusable block template. For simple one-page repeated content, prefer a repeating group (`[{ ... }]`). For reusable content selected across pages, prefer a collection entry plus `[entry(key)]`.
 
+### Stacks
+
+A **stack** is a heterogeneous list of blocks: each item picks its own block schema. Use a stack when a page section can contain a mix of different reusable components in an editor-chosen order. If every item would use the same block, prefer `[block(key)]` instead — stacks are for "section A could be a hero, a CTA, a quote, or a gallery."
+
+**Model syntax** — bare `stack`, no parentheses and no `[]`. Stacks are always multiple by definition:
+
+```
+{
+    title: text,
+    sections: stack
+}
+```
+
+Any block defined in `models/blocks/` may appear in any stack — the allowed set is the full block library, not a per-field allow-list.
+
+**Content shape** — an array of objects. Each item is shaped like the block model it uses, plus a `_block` marker naming that block by key (as a plain string):
+
+**`content/pages/about.json`**
+```json
+{
+    "title": "About us",
+    "sections": [
+        {
+            "_block": "hero",
+            "heading": "Care that feels personal",
+            "subheading": "A small team focused on long-term relationships.",
+            "background": "pexels:doctor"
+        },
+        {
+            "_block": "cta",
+            "label": "Book a visit",
+            "link": "/contact"
+        }
+    ]
+}
+```
+
+The `_block` value is the block's key (e.g., `"hero"`, `"cta"`) — never a numeric id. The CMS resolves it server-side on save.
+
+**Rendering** — each item flows through its own `blocks/<key>.ejs` template. Pass the whole array to `render()` and it dispatches per `_block`:
+
+**`pages/about.ejs`**
+```ejs
+<h1><%= item.title %></h1>
+<%- render(item.sections) %>
+```
+
+**Stack vs block vs collection** — same decision tree as blocks, with one extra rung:
+
+- One-off shape used on one page → group `{ ... }` or `[{ ... }]`.
+- Reusable shape, always the same per item → `block(key)` or `[block(key)]`.
+- Reusable shape, but items can be different blocks chosen by the editor → `stack`.
+- Shared content referenced from many pages → `entry(key)` / `[entry(key)]`.
+
+Like blocks, stacks cannot be nested inside block models. Stack items themselves may contain groups, collections, and entry references, but not other stacks or blocks.
+
 **Entry reference** — Use `entry(key)` for one, `[entry(key)]` for many:
 ```
 {
@@ -206,16 +263,19 @@ Model fields declare both the editor type and the shape expected in content JSON
 | `text`, `paragraph`, `richtext`, `markdown`, `code`, `color`, `link` | String |
 | `number` | Number |
 | `boolean` | `true` / `false` |
+| `emoji` | Single Unicode emoji character string, e.g. `"😀"` or `"👋🏽"` (one emoji per record; not free text) |
 | `date` | `"YYYY-MM-DD"` string |
 | `datetime` | ISO 8601 string |
 | `time` | `"HH:mm"` string |
 | `image` | Either a resolved `{ "url": "...", "alt": "..." }` object, **or** a shortcut string `"<source>:<search>"` (e.g., `"pexels:doctor"`, `"url:https://picsum.photos/200.jpg"`, `"cms:logo"`). Supported sources: `unsplash`, `pexels`, `pixabay`, `iconify`, `url`, `cms` (reuses an image declared in `/images.json` by handle). Append `\|<alt text>` to set the image's alt, e.g. `"pexels:doctor\|Smiling doctor with stethoscope"`. On save, the sync engine resolves the shortcut/link to a full image object automatically. |
-| `video` | `{ "url": "...", "embed": "..." }` |
+| `video` | Object of shape `{ "source": "BUNNY", "video_id": "...", "embed_url": "...", "title": "..." }`. **Do not write or invent this value.** Video uploads are user-driven in the CMS UI — the user uploads to Bunny.net and the sync engine stores the resolved object. In templates, always render videos with the `embed()` helper (e.g. `<%- embed(item.intro_video, { size: '1280x720' }) %>`), never by hand-rolling an iframe. |
+| `file` | Object of shape `{ "name": "...", "url": "...", "size": 0, "type": "...", "ext": "..." }` describing a downloadable document (PDF, CSV, DOC/DOCX, XLS/XLSX, PPT/PPTX, TSV, TXT — max 10 MB). **Do not write or invent this value.** File uploads are user-driven in the CMS UI — the user attaches the file via the editor and the sync engine stores the resolved object. In templates, render a link with `item.file.url` (download URL on `files.sleekcms.com`) and `item.file.name` (display name), e.g. `<a href="<%= item.brochure.url %>" download><%= item.brochure.name %></a>`. |
 | `json` | Object or array |
 | `sheet` | Array of arrays |
 | `location` | `{ "markers": [{ "lat": n, "lng": n }], "img": "..." }`; `img` is a Google Maps Static Image URL that already includes the markers and can include formatting parameters such as `size`, `zoom`, `scale`, `maptype`, and styling |
 | `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 |
 | Group `{ ... }` | Nested object |
 | Collection `[{ ... }]` | Array of nested objects |
@@ -232,10 +292,11 @@ Content files are JSON records under `/content/` that hold the actual values for
 
 ### File layout
 
-| Model shape | File path | JSON top-level |
+| Model shape | File path | Top-level shape |
 |---|---|---|
 | Single page (e.g., `about`) | `content/pages/about.json` | Object |
 | Collection page (e.g., `blog+`) | `content/pages/blog+/<slug>.json` (the `+` is part of the key, not an extra suffix) | Object; one file per slug |
+| Collection page with one markdown body (see below) | `content/pages/blog+/<slug>.md` | YAML frontmatter + markdown body |
 | Single entry (e.g., `header`) | `content/entries/header.json` | Object |
 | Collection entry (e.g., `authors`) | `content/entries/authors+.json` (the `+` is part of the key — same as the model filename) | Array of objects |
 
@@ -266,6 +327,69 @@ The content file at `content/pages/about.json`:
 
 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.
 
+### Markdown content files
+
+For a **collection page** whose model is shaped like "metadata + one long-form body", the sync engine stores each record as a **Markdown file with JSON frontmatter** (`.md`) instead of `.json`. The body is plain Markdown; the metadata is a JSON object between `---` markers.
+
+A model qualifies when **all** of the following hold:
+
+1. It is a **page** model (lives in `models/pages/`).
+2. It is a **collection** (key ends with `+`, so each record is its own file).
+3. It has **exactly one** top-level field of type `markdown`.
+4. It has **no** `richtext` or `stack` fields anywhere (top-level or nested).
+
+When the model qualifies, content lives at `content/pages/<key+>/<slug>.md`. All non-markdown fields go into the JSON frontmatter; the single `markdown` field's value becomes the body.
+
+Example — given the model `models/pages/blog+.model`:
+
+```
+{
+    title: text,
+    date: date,
+    summary: paragraph,
+    body: markdown
+}
+```
+
+The record `content/pages/blog+/welcome-post.md` looks like:
+
+```markdown
+---
+{
+  "title": "Welcome to the blog",
+  "date": "2026-05-19",
+  "summary": "A short post about how the new blog works."
+}
+---
+# Hello
+
+This is the **first** post.
+
+- one
+- two
+```
+
+Notes:
+- The body field's handle (`body` above) is whatever the single `markdown` field is called in the model — its key never appears in the frontmatter; its value is the markdown content.
+- Image shortcut conventions still apply inside the markdown body (`![alt](pexels:doctor)`) and inside frontmatter image fields (`"pexels:doctor"`).
+- If the model doesn't qualify (e.g., it has two markdown fields, or a `stack`), the content stays JSON at `content/pages/<key+>/<slug>.json` — no change.
+- The server still accepts `.json` for qualifying models — sending `.md` is preferred but not required. The next pull will re-emit the canonical `.md` form.
+
+**YAML frontmatter is also accepted as input.** The server detects whichever shape you write between the `---` markers and parses it correctly. The canonical form emitted by the server is JSON — on the next pull, YAML frontmatter is rewritten to JSON.
+
+```markdown
+---
+title: Welcome to the blog
+date: '2026-05-19'
+summary: A short post.
+---
+# Hello
+
+This is the **first** post.
+```
+
+JSON5 features (trailing commas, `//` or `/* */` comments, unquoted keys) are accepted in JSON frontmatter. Choose JSON for programmatic generation (and to match canonical output); YAML is fine for hand-edits.
+
 ### Reusable images (`/images.json`)
 
 For images used in more than one place (logos, recurring icons, hero art), declare them once in `/images.json` as a flat map of `handle → shortcut` using the same shortcut convention as `image` fields:
@@ -356,6 +480,25 @@ Page records include: `item._path`, `item._slug` (collections), `item._meta.upda
 
 `attr` can be `"WxH"` or `{ w, h, size, zoom, maptype, scale, class, style }`.
 
+### Video
+
+`video` field content is created by the user via the CMS UI (uploading to Bunny.net). **The agent must never write a value into a `video` field, build an `<iframe>` tag by hand, or guess a `video_id` / `embed_url`.** Always render a video by passing the field object to the `embed()` helper.
+
+| Function | Returns | Description |
+|---|---|---|
+| `embed(video, attr?)` | HTML string | Provider-aware `<iframe>` for the video |
+
+`attr` is `"WxH"` or `{ w, h, size, autoplay, muted, loop, preload, t, class, style }`.
+
+```ejs
+<%- embed(item.intro_video) %>
+<%- embed(item.intro_video, '1280x720') %>
+<%- embed(item.intro_video, { autoplay: true, muted: true, loop: true }) %>
+<%- embed(item.intro_video, { size: '800x450', class: 'video', style: 'border-radius:8px' }) %>
+```
+
+Most browsers block autoplay unless `muted: true` is also set. `autoplay` is added to the iframe's `allow` attribute only when the caller opts in.
+
 ### Head Injection
 
 Call from **any template** (page, block, entry, or layout). Deduplicated automatically.
@@ -564,5 +707,6 @@ Template:
 13. Block models cannot contain `block(...)` fields. Use groups, collections, or `entry(key)` references instead.
 14. For `image` fields in content JSON, prefer the shortcut form `"<source>:<search>"` (sources: `unsplash`, `pexels`, `pixabay`, `iconify`) — e.g., `"pexels:doctor"`. Add alt text by appending `|<alt>` to the shortcut: `"pexels:doctor|Smiling doctor with stethoscope"`. The sync engine resolves it to a full `{ url, alt }` object on save. When the same image is reused across pages (logos, shared icons, recurring art), declare it once in `/images.json` and reference it via `"cms:<handle>"`.
 15. Inside `markdown` fields, embed images with `![alt](<source>:<search>)` — same sources as image fields. Append `|<alt>` to store alt on the image record (e.g. `![doctor](pexels:doctor|Friendly family doctor)`). Including a `<W>x<H>` token in the description (e.g. `|hero shot 1200x600`) sets the rendered URL's `w` and `h` query params; otherwise the default is `600x400`. On save, refs are rewritten to actual CDN URLs and the underlying image record is created automatically.
-16. Always create RSS feed for blogs and link them in meta so it is discoverable. Use "rss.xml" as the key.
-17. Make the sites extremely SEO friendly and sharing friendly.
+16. **Collection pages whose model qualifies as "markdown content" — page model, collection (key ends with `+`), exactly one top-level `markdown` field, no `richtext` or `stack` anywhere — are stored as `.md` files with JSON frontmatter at `content/pages/<key+>/<slug>.md` (not `.json`).** All non-markdown fields go into the JSON frontmatter object between the `---` markers; the single `markdown` field's value is the body. When creating or editing such a record, prefer `.md`; the server also accepts `.json` for the same model. Inside the `.md` file, frontmatter may be written as JSON (canonical), JSON5 (trailing commas, `//` or `/* */` comments, unquoted keys), or YAML — all three are parsed correctly on save. Pulls always re-emit JSON as the canonical form.
+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.

package/dist/watcher.js

@@ -19,10 +19,15 @@ const path_1 = __importDefault(require("path"));
 const chokidar_1 = __importDefault(require("chokidar"));
 const DEBOUNCE_DELAY = 5000;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+// Poll on a short interval and compare wall-clock time so the timeout still
+// fires correctly after the system has been asleep (Node's setTimeout runs on
+// a monotonic clock that pauses during sleep).
+const IDLE_CHECK_INTERVAL_MS = 60 * 1000;
 let watcher = null;
 let isShuttingDown = false;
 let debounceTimer = null;
-let idleTimer = null;
+let idleCheckTimer = null;
+let lastActivityAt = 0;
 let dirty = false;
 let syncInFlight = false;
 let viewsDir = null;
@@ -34,17 +39,23 @@ function init(options) {
     onIdle = options.onIdle ?? null;
 }
 function resetIdleTimer() {
-    if (idleTimer)
-        clearTimeout(idleTimer);
+    lastActivityAt = Date.now();
     if (isShuttingDown || !onIdle)
         return;
-    idleTimer = setTimeout(() => {
-        idleTimer = null;
+    if (idleCheckTimer)
+        return;
+    idleCheckTimer = setInterval(() => {
         if (isShuttingDown)
             return;
+        if (Date.now() - lastActivityAt < IDLE_TIMEOUT_MS)
+            return;
+        if (idleCheckTimer) {
+            clearInterval(idleCheckTimer);
+            idleCheckTimer = null;
+        }
         console.log(`\n💤 No changes for ${IDLE_TIMEOUT_MS / 60000} minutes. Terminating.`);
         onIdle?.();
-    }, IDLE_TIMEOUT_MS);
+    }, IDLE_CHECK_INTERVAL_MS);
 }
 function setShuttingDown(value) {
     isShuttingDown = value;
@@ -100,9 +111,9 @@ function monitorFiles() {
     resetIdleTimer();
 }
 async function stopWatching() {
-    if (idleTimer) {
-        clearTimeout(idleTimer);
-        idleTimer = null;
+    if (idleCheckTimer) {
+        clearInterval(idleCheckTimer);
+        idleCheckTimer = null;
     }
     if (watcher) {
         await watcher.close();

package/package.json

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