@riverbankcms/sdk 0.5.0 → 0.5.2

package/dist/cli/index.js

@@ -7,7 +7,8 @@ var fs = require('fs');
 var dotenv = require('dotenv');
 var commander = require('commander');
 var zod = require('zod');
-var fs5 = require('fs/promises');
+var prompts = require('prompts');
+var fs3 = require('fs/promises');
 var readline = require('readline');
 var equal = require('fast-deep-equal');
 var os = require('os');
@@ -35,7 +36,8 @@ function _interopNamespace(e) {
 }
 
 var path9__namespace = /*#__PURE__*/_interopNamespace(path9);
-var fs5__namespace = /*#__PURE__*/_interopNamespace(fs5);
+var prompts__default = /*#__PURE__*/_interopDefault(prompts);
+var fs3__namespace = /*#__PURE__*/_interopNamespace(fs3);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
 var equal__default = /*#__PURE__*/_interopDefault(equal);
 var os__namespace = /*#__PURE__*/_interopNamespace(os);
@@ -5480,66 +5482,6 @@ Examples:
   const dashboard = resolveDashboardUrl(options.dashboard);
   return pushConfigAction({ ...options, dashboard });
 });
-async function ensureDir(dirPath) {
-  try {
-    await fs5__namespace.mkdir(dirPath, { recursive: true });
-  } catch (error) {
-    if (error.code !== "EEXIST") {
-      throw error;
-    }
-  }
-}
-async function writeJsonFile(filePath, data) {
-  const content = JSON.stringify(data, null, 2) + "\n";
-  await fs5__namespace.writeFile(filePath, content, "utf-8");
-}
-async function writeEntries(contentDir, pulledEntries) {
-  const entriesDir = path9__namespace.join(contentDir, "entries");
-  const metaDir = path9__namespace.join(contentDir, ".meta");
-  await ensureDir(entriesDir);
-  await ensureDir(metaDir);
-  const { contentType, entries, meta } = pulledEntries;
-  const entriesFile = {
-    contentType,
-    entries: entries.map((entry) => ({
-      identifier: entry.identifier,
-      data: entry.data,
-      status: entry.status,
-      hasUnpublishedChanges: entry.hasUnpublishedChanges,
-      slug: entry.slug
-    }))
-  };
-  const filePath = path9__namespace.join(entriesDir, `${contentType}.json`);
-  await writeJsonFile(filePath, entriesFile);
-  const metaPath = path9__namespace.join(metaDir, `${contentType}.json`);
-  await writeJsonFile(metaPath, meta);
-  return { filePath, metaPath };
-}
-async function writePages(contentDir, pulledPages) {
-  const pagesDir = path9__namespace.join(contentDir, "pages");
-  await ensureDir(pagesDir);
-  const filePaths = [];
-  for (const page of pulledPages.pages) {
-    const filePath = path9__namespace.join(pagesDir, `${page.identifier}.json`);
-    await writeJsonFile(filePath, page);
-    filePaths.push(filePath);
-  }
-  return filePaths;
-}
-async function writeNavigation(contentDir, pulledNavigation) {
-  await ensureDir(contentDir);
-  const filePath = path9__namespace.join(contentDir, "navigation.json");
-  await writeJsonFile(filePath, {
-    menus: pulledNavigation.menus
-  });
-  return filePath;
-}
-async function writeSettings(contentDir, pulledSettings) {
-  await ensureDir(contentDir);
-  const filePath = path9__namespace.join(contentDir, "settings.json");
-  await writeJsonFile(filePath, pulledSettings.settings);
-  return filePath;
-}
 
 // src/client/management/http.ts
 var ManagementApiError = class extends Error {
@@ -5828,12 +5770,15 @@ function createPullOperations(http) {
         http.get("/pull/settings")
       ]);
       return {
-        entries: entriesResult.entries,
-        pages: pagesResult.pages,
-        navigation: navigationResult.menus,
-        settings: settingsResult.settings,
+        entries: entriesResult?.entries || {},
+        pages: pagesResult?.pages || [],
+        navigation: navigationResult?.menus || [],
+        settings: settingsResult?.settings || {},
         meta: {
-          pulledAt: (/* @__PURE__ */ new Date()).toISOString()
+          pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
+          entries: entriesResult?.meta?.entries,
+          truncated: entriesResult?.meta?.truncated,
+          truncationMessage: entriesResult?.meta?.truncationMessage
         }
       };
     }
@@ -5849,6 +5794,15 @@ function createPreviewOperations(http) {
   };
 }
 
+// src/client/management/identifiers.ts
+function createIdentifiersOperations(http) {
+  return {
+    async backfill() {
+      return http.post("/identifiers/backfill");
+    }
+  };
+}
+
 // src/client/management/index.ts
 function createManagementClient(config3) {
   if (!config3.dashboardUrl) {
@@ -5879,7 +5833,8 @@ function createManagementClient(config3) {
     navigation: createNavigationOperations(http),
     settings: createSettingsOperations(http),
     pull: createPullOperations(http),
-    preview: createPreviewOperations(http)
+    preview: createPreviewOperations(http),
+    identifiers: createIdentifiersOperations(http)
   };
 }
 
@@ -6063,6 +6018,18 @@ function formatError(error) {
 }
 
 // src/cli/helpers.ts
+function mapEntryForOutput(entry) {
+  const result = {
+    identifier: entry.identifier,
+    data: entry.data,
+    status: entry.status,
+    hasUnpublishedChanges: entry.hasUnpublishedChanges
+  };
+  if (entry.slug !== void 0) {
+    result.slug = entry.slug;
+  }
+  return result;
+}
 function parsePaginationOptions(options) {
   return {
     limit: parseInt(options.limit ?? "20", 10),
@@ -6075,7 +6042,7 @@ function formatDateShort(isoDate) {
 async function parseJsonData(options) {
   if (options.file) {
     const filePath = path9__namespace.resolve(options.file);
-    const content = await fs5__namespace.readFile(filePath, "utf-8");
+    const content = await fs3__namespace.readFile(filePath, "utf-8");
     return JSON.parse(content);
   }
   if (options.data) {
@@ -6280,20 +6247,253 @@ function createListCommand(config3) {
   );
 }
 
+// src/cli/content/writer.ts
+async function ensureDir(dirPath) {
+  try {
+    await fs3__namespace.mkdir(dirPath, { recursive: true });
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+  }
+}
+async function writeJsonFile(filePath, data) {
+  const content = JSON.stringify(data, null, 2) + "\n";
+  await fs3__namespace.writeFile(filePath, content, "utf-8");
+}
+async function writeEntries(contentDir, pulledEntries) {
+  const entriesDir = path9__namespace.join(contentDir, "entries");
+  const metaDir = path9__namespace.join(contentDir, ".meta");
+  await ensureDir(entriesDir);
+  await ensureDir(metaDir);
+  const { contentType, entries, meta } = pulledEntries;
+  const entriesFile = {
+    contentType,
+    entries: entries.map(mapEntryForOutput)
+  };
+  const filePath = path9__namespace.join(entriesDir, `${contentType}.json`);
+  await writeJsonFile(filePath, entriesFile);
+  const metaPath = path9__namespace.join(metaDir, `${contentType}.json`);
+  await writeJsonFile(metaPath, meta);
+  return { filePath, metaPath };
+}
+async function writePages(contentDir, pulledPages) {
+  const pagesDir = path9__namespace.join(contentDir, "pages");
+  const metaDir = path9__namespace.join(contentDir, ".meta");
+  await ensureDir(pagesDir);
+  await ensureDir(metaDir);
+  const filePaths = [];
+  const pagesMeta = {};
+  for (const page of pulledPages.pages) {
+    const filePath = path9__namespace.join(pagesDir, `${page.identifier}.json`);
+    await writeJsonFile(filePath, page);
+    filePaths.push(filePath);
+    pagesMeta[page.identifier] = {
+      createdAt: page.createdAt,
+      updatedAt: page.updatedAt
+    };
+  }
+  const metaPath = path9__namespace.join(metaDir, "pages.json");
+  await writeJsonFile(metaPath, {
+    pulledAt: pulledPages.meta.pulledAt,
+    pages: pagesMeta
+  });
+  return { filePaths, metaPath };
+}
+async function writeNavigation(contentDir, pulledNavigation) {
+  const metaDir = path9__namespace.join(contentDir, ".meta");
+  await ensureDir(contentDir);
+  await ensureDir(metaDir);
+  const filePath = path9__namespace.join(contentDir, "navigation.json");
+  await writeJsonFile(filePath, {
+    menus: pulledNavigation.menus
+  });
+  const menusMeta = {};
+  for (const menu of pulledNavigation.menus) {
+    menusMeta[menu.name] = {
+      createdAt: menu.createdAt,
+      updatedAt: menu.updatedAt
+    };
+  }
+  const metaPath = path9__namespace.join(metaDir, "navigation.json");
+  await writeJsonFile(metaPath, {
+    pulledAt: pulledNavigation.meta.pulledAt,
+    menus: menusMeta
+  });
+  return { filePath, metaPath };
+}
+async function writeSettings(contentDir, pulledSettings) {
+  await ensureDir(contentDir);
+  const filePath = path9__namespace.join(contentDir, "settings.json");
+  await writeJsonFile(filePath, pulledSettings.settings);
+  return filePath;
+}
+async function fileExists(filePath) {
+  try {
+    await fs3__namespace.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsonFile(filePath) {
+  const content = await fs3__namespace.readFile(filePath, "utf-8");
+  return JSON.parse(content);
+}
+async function listFiles(dirPath, extension) {
+  try {
+    const files = await fs3__namespace.readdir(dirPath);
+    return files.filter((f) => f.endsWith(extension)).map((f) => path9__namespace.join(dirPath, f));
+  } catch {
+    return [];
+  }
+}
+async function readEntries(contentDir, contentType) {
+  const entriesDir = path9__namespace.join(contentDir, "entries");
+  const result = /* @__PURE__ */ new Map();
+  {
+    const files = await listFiles(entriesDir, ".json");
+    for (const filePath of files) {
+      try {
+        const file = await readJsonFile(filePath);
+        result.set(file.contentType, file.entries);
+      } catch (error) {
+        console.warn(`Warning: Could not parse ${filePath}:`, error);
+      }
+    }
+  }
+  return result;
+}
+async function readPages(contentDir) {
+  const pagesDir = path9__namespace.join(contentDir, "pages");
+  const pages = [];
+  const files = await listFiles(pagesDir, ".json");
+  for (const filePath of files) {
+    try {
+      const page = await readJsonFile(filePath);
+      pages.push(page);
+    } catch (error) {
+      console.warn(`Warning: Could not parse ${filePath}:`, error);
+    }
+  }
+  return pages;
+}
+async function readNavigation(contentDir) {
+  const filePath = path9__namespace.join(contentDir, "navigation.json");
+  if (!await fileExists(filePath)) {
+    return null;
+  }
+  return readJsonFile(filePath);
+}
+async function readSettings(contentDir) {
+  const filePath = path9__namespace.join(contentDir, "settings.json");
+  if (!await fileExists(filePath)) {
+    return null;
+  }
+  return readJsonFile(filePath);
+}
+async function readAllContent(contentDir) {
+  const [entries, pages, navigation, settings] = await Promise.all([
+    readEntries(contentDir),
+    readPages(contentDir),
+    readNavigation(contentDir),
+    readSettings(contentDir)
+  ]);
+  return { entries, pages, navigation, settings };
+}
+async function contentDirExists(contentDir) {
+  return fileExists(contentDir);
+}
+async function getContentSummary(contentDir) {
+  const content = await readAllContent(contentDir);
+  const entryTypes = Array.from(content.entries.keys());
+  let totalEntries = 0;
+  for (const entries of content.entries.values()) {
+    totalEntries += entries.length;
+  }
+  return {
+    hasEntries: content.entries.size > 0,
+    entryTypes,
+    totalEntries,
+    hasPages: content.pages.length > 0,
+    pageCount: content.pages.length,
+    hasNavigation: content.navigation !== null && content.navigation.menus.length > 0,
+    menuCount: content.navigation?.menus.length ?? 0,
+    hasSettings: content.settings !== null
+  };
+}
+async function readEntriesMeta(contentDir, contentType) {
+  const metaPath = path9__namespace.join(contentDir, ".meta", `${contentType}.json`);
+  try {
+    const content = await fs3__namespace.readFile(metaPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+async function readAllMeta(contentDir) {
+  const metaDir = path9__namespace.join(contentDir, ".meta");
+  const metaMap = /* @__PURE__ */ new Map();
+  try {
+    const files = await fs3__namespace.readdir(metaDir);
+    for (const file of files) {
+      if (file.endsWith(".json") && file !== "pages.json" && file !== "navigation.json") {
+        const contentType = file.replace(".json", "");
+        const meta = await readEntriesMeta(contentDir, contentType);
+        if (meta) metaMap.set(contentType, meta);
+      }
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return metaMap;
+}
+async function readPagesMeta(contentDir) {
+  const metaPath = path9__namespace.join(contentDir, ".meta", "pages.json");
+  try {
+    const content = await fs3__namespace.readFile(metaPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+async function readNavigationMeta(contentDir) {
+  const metaPath = path9__namespace.join(contentDir, ".meta", "navigation.json");
+  try {
+    const content = await fs3__namespace.readFile(metaPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
 // src/cli/commands/pull.ts
 var DEFAULT_PAGE_LIMIT = 500;
 async function pullEntriesWithPagination(client, contentType, output) {
   const allEntries = [];
+  const aggregatedMeta = {};
   let page = 1;
   let hasMore = true;
-  let lastResult = null;
+  let pulledAt = (/* @__PURE__ */ new Date()).toISOString();
   while (hasMore) {
     const result = await client.pull.entries(contentType, {
       page,
       limit: DEFAULT_PAGE_LIMIT
     });
     allEntries.push(...result.entries);
-    lastResult = result;
+    if (result.meta.entries) {
+      Object.assign(aggregatedMeta, result.meta.entries);
+    }
+    pulledAt = result.meta.pulledAt;
     hasMore = result.pagination.hasMore;
     if (hasMore) {
       output.info(`Fetched ${allEntries.length} entries (page ${page})...`);
@@ -6303,7 +6503,7 @@ async function pullEntriesWithPagination(client, contentType, output) {
   return {
     contentType,
     entries: allEntries,
-    meta: lastResult?.meta ?? { pulledAt: (/* @__PURE__ */ new Date()).toISOString(), entries: {} },
+    meta: { pulledAt, entries: aggregatedMeta },
     pagination: {
       page: 1,
       limit: allEntries.length,
@@ -6312,20 +6512,21 @@ async function pullEntriesWithPagination(client, contentType, output) {
     }
   };
 }
-async function writeAllEntries(contentDir, entriesByType, pulledAt) {
+async function writeAllEntries(contentDir, entriesByType, pulledAt, entriesMeta) {
   let totalCount = 0;
   const files = [];
   for (const [contentType, entries] of Object.entries(entriesByType)) {
+    const ctMeta = {};
+    for (const entry of entries) {
+      const key = `${contentType}:${entry.identifier}`;
+      if (entriesMeta?.[key]) {
+        ctMeta[entry.identifier] = entriesMeta[key];
+      }
+    }
     const { filePath } = await writeEntries(contentDir, {
       contentType,
-      entries: entries.map((e) => ({
-        identifier: e.identifier,
-        data: e.data,
-        status: e.status,
-        hasUnpublishedChanges: e.hasUnpublishedChanges,
-        slug: e.slug
-      })),
-      meta: { pulledAt, entries: {} },
+      entries,
+      meta: { pulledAt, entries: ctMeta },
       pagination: { limit: entries.length, total: entries.length}
     });
     totalCount += entries.length;
@@ -6335,16 +6536,14 @@ async function writeAllEntries(contentDir, entriesByType, pulledAt) {
 }
 async function fetchAllContentPaginated(client, contentTypes, output) {
   const allEntries = {};
+  const allMeta = {};
   for (const contentType of contentTypes) {
     output.info(`Fetching ${contentType} entries...`);
     const result = await pullEntriesWithPagination(client, contentType, output);
-    allEntries[contentType] = result.entries.map((e) => ({
-      identifier: e.identifier,
-      data: e.data,
-      status: e.status,
-      hasUnpublishedChanges: e.hasUnpublishedChanges,
-      slug: e.slug
-    }));
+    allEntries[contentType] = result.entries.map(mapEntryForOutput);
+    for (const [id, meta] of Object.entries(result.meta.entries || {})) {
+      allMeta[`${contentType}:${id}`] = meta;
+    }
     output.info(`  ${result.entries.length} entries`);
   }
   output.info("Fetching pages...");
@@ -6358,10 +6557,10 @@ async function fetchAllContentPaginated(client, contentTypes, output) {
     pages: pagesResult.pages,
     navigation: navigationResult.menus,
     settings: settingsResult.settings,
-    meta: { pulledAt: (/* @__PURE__ */ new Date()).toISOString() }
+    meta: { pulledAt: (/* @__PURE__ */ new Date()).toISOString(), entries: allMeta }
   };
 }
-var pullCommand = new commander.Command("pull").description("Pull content from CMS").argument("[scope]", "What to pull: entries, pages, navigation, settings, or all (default)").argument("[type]", 'Content type (when scope is "entries")').option("--output <dir>", "Output directory", "./content").addHelpText("after", `
+var pullCommand = new commander.Command("pull").description("Pull content from CMS").argument("[scope]", "What to pull: entries, pages, navigation, settings, or all (default)").argument("[type]", 'Content type (when scope is "entries")').option("--output <dir>", "Output directory", "./content").option("--force", "Overwrite existing files without prompting").option("--yes", "Skip confirmation prompt (same as --force)").addHelpText("after", `
 Examples:
   $ riverbankcms pull                         # Pull all content
   $ riverbankcms pull --remote                # Pull from production
@@ -6376,6 +6575,24 @@ Examples:
     async (scope, type, options, command) => {
       const { output, client } = createCommandContext(command);
       const contentDir = path9__namespace.resolve(options.output ?? "./content");
+      if (await contentDirExists(contentDir) && !options.force && !options.yes) {
+        if (!process.stdin.isTTY) {
+          output.error("Content directory already exists and --yes not specified", {
+            suggestion: "Use --yes or --force to overwrite in non-interactive mode"
+          });
+          return;
+        }
+        const response = await prompts__default.default({
+          type: "confirm",
+          name: "overwrite",
+          message: `Content directory '${path9__namespace.basename(contentDir)}' already exists. Overwrite?`,
+          initial: false
+        });
+        if (!response.overwrite) {
+          output.info("Aborted.");
+          return;
+        }
+      }
       const pullScope = scope?.toLowerCase() ?? "all";
       switch (pullScope) {
         case "entries": {
@@ -6400,7 +6617,8 @@ Examples:
             const { totalCount, files } = await writeAllEntries(
               contentDir,
               result.entries,
-              result.meta.pulledAt
+              result.meta.pulledAt,
+              result.meta.entries
             );
             output.success(`Pulled ${totalCount} entries across ${Object.keys(result.entries).length} content types`, {
               files
@@ -6411,15 +6629,15 @@ Examples:
         case "pages": {
           output.info("Pulling pages");
           const result = await client.pull.pages();
-          const files = await writePages(contentDir, result);
-          output.success(`Pulled ${result.pages.length} pages`, { files });
+          const { filePaths, metaPath } = await writePages(contentDir, result);
+          output.success(`Pulled ${result.pages.length} pages`, { files: filePaths, meta: metaPath });
           break;
         }
         case "navigation": {
           output.info("Pulling navigation menus");
           const result = await client.pull.navigation();
-          const filePath = await writeNavigation(contentDir, result);
-          output.success(`Pulled ${result.menus.length} navigation menus`, { file: filePath });
+          const { filePath, metaPath } = await writeNavigation(contentDir, result);
+          output.success(`Pulled ${result.menus.length} navigation menus`, { file: filePath, meta: metaPath });
           break;
         }
         case "settings": {
@@ -6442,7 +6660,8 @@ Examples:
           const { totalCount: totalEntries } = await writeAllEntries(
             contentDir,
             result.entries,
-            result.meta.pulledAt
+            result.meta.pulledAt,
+            result.meta.entries
           );
           await writePages(contentDir, { pages: result.pages, meta: result.meta });
           await writeNavigation(contentDir, { menus: result.navigation, meta: result.meta });
@@ -6489,100 +6708,6 @@ async function loadCliConfig(configPath) {
     throw error;
   }
 }
-async function fileExists(filePath) {
-  try {
-    await fs5__namespace.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function readJsonFile(filePath) {
-  const content = await fs5__namespace.readFile(filePath, "utf-8");
-  return JSON.parse(content);
-}
-async function listFiles(dirPath, extension) {
-  try {
-    const files = await fs5__namespace.readdir(dirPath);
-    return files.filter((f) => f.endsWith(extension)).map((f) => path9__namespace.join(dirPath, f));
-  } catch {
-    return [];
-  }
-}
-async function readEntries(contentDir, contentType) {
-  const entriesDir = path9__namespace.join(contentDir, "entries");
-  const result = /* @__PURE__ */ new Map();
-  {
-    const files = await listFiles(entriesDir, ".json");
-    for (const filePath of files) {
-      try {
-        const file = await readJsonFile(filePath);
-        result.set(file.contentType, file.entries);
-      } catch (error) {
-        console.warn(`Warning: Could not parse ${filePath}:`, error);
-      }
-    }
-  }
-  return result;
-}
-async function readPages(contentDir) {
-  const pagesDir = path9__namespace.join(contentDir, "pages");
-  const pages = [];
-  const files = await listFiles(pagesDir, ".json");
-  for (const filePath of files) {
-    try {
-      const page = await readJsonFile(filePath);
-      pages.push(page);
-    } catch (error) {
-      console.warn(`Warning: Could not parse ${filePath}:`, error);
-    }
-  }
-  return pages;
-}
-async function readNavigation(contentDir) {
-  const filePath = path9__namespace.join(contentDir, "navigation.json");
-  if (!await fileExists(filePath)) {
-    return null;
-  }
-  return readJsonFile(filePath);
-}
-async function readSettings(contentDir) {
-  const filePath = path9__namespace.join(contentDir, "settings.json");
-  if (!await fileExists(filePath)) {
-    return null;
-  }
-  return readJsonFile(filePath);
-}
-async function readAllContent(contentDir) {
-  const [entries, pages, navigation, settings] = await Promise.all([
-    readEntries(contentDir),
-    readPages(contentDir),
-    readNavigation(contentDir),
-    readSettings(contentDir)
-  ]);
-  return { entries, pages, navigation, settings };
-}
-async function contentDirExists(contentDir) {
-  return fileExists(contentDir);
-}
-async function getContentSummary(contentDir) {
-  const content = await readAllContent(contentDir);
-  const entryTypes = Array.from(content.entries.keys());
-  let totalEntries = 0;
-  for (const entries of content.entries.values()) {
-    totalEntries += entries.length;
-  }
-  return {
-    hasEntries: content.entries.size > 0,
-    entryTypes,
-    totalEntries,
-    hasPages: content.pages.length > 0,
-    pageCount: content.pages.length,
-    hasNavigation: content.navigation !== null && content.navigation.menus.length > 0,
-    menuCount: content.navigation?.menus.length ?? 0,
-    hasSettings: content.settings !== null
-  };
-}
 
 // src/cli/sync/mapper.ts
 function stripNavigationItemIds(items) {
@@ -7365,7 +7490,48 @@ function reportSyncResults(output, result, hasErrors) {
   }
   output.info(formatSyncResult(result));
 }
-var pushCommand = new commander.Command("push").description("Push content to CMS").argument("[scope]", "What to push: entries, pages, navigation, or all (default)").argument("[type]", 'Content type (when scope is "entries")').option("--content-dir <dir>", "Content directory (overrides config)").option("--dry-run", "Show what would be pushed without making changes").option("--yes", "Skip confirmation prompt (required for --remote)").option("--force", "Push even if remote content was truncated (may cause incomplete sync)").option("--json-diff [mode]", "Output JSON diff (summary or full)", "summary").addHelpText("after", `
+function checkForStaleContent(localContent, localMeta, pagesMeta, navigationMeta, remoteContent) {
+  const staleItems = [];
+  for (const [contentType, localEntries] of localContent.entries) {
+    const meta = localMeta.get(contentType);
+    if (!meta) continue;
+    remoteContent.entries[contentType]?.forEach((remoteEntry) => {
+      const localEntry = localEntries.find((e) => e.identifier === remoteEntry.identifier);
+      if (localEntry) {
+        const entryMeta = meta.entries[remoteEntry.identifier];
+        const localBaseTime = entryMeta?.updatedAt;
+        const remoteTime = remoteContent.meta.entries?.[`${contentType}:${remoteEntry.identifier}`]?.updatedAt;
+        if (localBaseTime && remoteTime && new Date(remoteTime) > new Date(localBaseTime)) {
+          staleItems.push(`Entry: ${contentType}/${remoteEntry.identifier} (Remote updated: ${remoteTime})`);
+        }
+      }
+    });
+  }
+  if (pagesMeta) {
+    localContent.pages.forEach((localPage) => {
+      const remotePage = remoteContent.pages.find((p) => p.identifier === localPage.identifier);
+      const localBaseTime = pagesMeta.pages[localPage.identifier]?.updatedAt;
+      if (remotePage && localBaseTime) {
+        if (new Date(remotePage.updatedAt) > new Date(localBaseTime)) {
+          staleItems.push(`Page: ${localPage.identifier} (Remote updated: ${remotePage.updatedAt})`);
+        }
+      }
+    });
+  }
+  if (navigationMeta) {
+    localContent.navigation?.menus.forEach((localMenu) => {
+      const remoteMenu = remoteContent.navigation.find((m) => m.name === localMenu.name);
+      const localBaseTime = navigationMeta.menus[localMenu.name]?.updatedAt;
+      if (remoteMenu && localBaseTime) {
+        if (new Date(remoteMenu.updatedAt) > new Date(localBaseTime)) {
+          staleItems.push(`Navigation: ${localMenu.name} (Remote updated: ${remoteMenu.updatedAt})`);
+        }
+      }
+    });
+  }
+  return staleItems;
+}
+var pushCommand = new commander.Command("push").description("Push content to CMS").argument("[scope]", "What to push: entries, pages, navigation, or all (default)").argument("[type]", 'Content type (when scope is "entries")').option("--content-dir <dir>", "Content directory (overrides config)").option("--dry-run", "Show what would be pushed without making changes").option("--yes", "Skip confirmation prompt (required for --remote)").option("--force", "Push even if remote content is newer (skip stale check)").option("--allow-truncated", "Push even if remote content was truncated (may cause incomplete sync)").option("--json-diff [mode]", "Output JSON diff (summary or full)", "summary").addHelpText("after", `
 Examples:
   $ riverbankcms push                         # Push all content
   $ riverbankcms push --dry-run               # Preview changes
@@ -7384,9 +7550,9 @@ Sync Behavior:
   - sync.contentTarget: 'draft' (default) or 'publish'
 
 Safety:
-  - Local environment: pushes directly
+  - Stale detection: aborts if remote content is newer than last pull (use --force to override)
+  - Truncation: aborts if remote has >100 entries per type (use --allow-truncated to override)
   - Remote environment (--remote): defaults to dry-run, requires --yes to execute
-  - Use --dry-run to preview changes before pushing
 `).action(async (scope, type, options, command) => {
   const { output, isRemote, globalOpts } = getOutputContext(command);
   let dryRun = options.dryRun ?? false;
@@ -7420,24 +7586,42 @@ Safety:
     });
     output.info("Reading local content...");
     const localContent = await readAllContent(contentDir);
+    const pushScope = scope?.toLowerCase() ?? "all";
+    const filteredLocal = filterLocalContent(localContent, pushScope, type);
     output.info("Fetching remote content for comparison...");
     const remoteContent = await client.pull.all();
     if (remoteContent.meta.truncated) {
       output.warn("Warning: Remote content was truncated due to size limits.");
       output.warn(
-        remoteContent.meta.truncationMessage ?? "Some content types have more than 500 entries. Results may be incomplete."
+        remoteContent.meta.truncationMessage ?? "Some content types have more than 100 entries. Results may be incomplete."
       );
-      if (!options.force) {
+      if (!options.allowTruncated) {
+        output.error(
+          "Push aborted due to truncated remote content.",
+          { suggestion: "Use --allow-truncated to push anyway, or push specific content types: riverbankcms push entries blog-post" }
+        );
+        return;
+      }
+      output.warn("Proceeding with push despite truncation (--allow-truncated flag used)");
+    }
+    if (!options.force) {
+      output.info("Checking for stale content...");
+      const [localMeta, pagesMeta, navigationMeta] = await Promise.all([
+        readAllMeta(contentDir),
+        readPagesMeta(contentDir),
+        readNavigationMeta(contentDir)
+      ]);
+      const staleItems = checkForStaleContent(filteredLocal, localMeta, pagesMeta, navigationMeta, remoteContent);
+      if (staleItems.length > 0) {
+        output.warn("WARNING: The following remote content has changed since you last pulled:");
+        staleItems.forEach((item) => output.warn(`  - ${item}`));
         output.error(
-          "Use --force to push anyway, or use type-specific pulls for accuracy.",
-          { suggestion: "For large sites, push specific content types: riverbankcms push entries blog-post" }
+          "Push aborted to prevent overwriting newer content.",
+          { suggestion: 'Run "riverbankcms pull" to update your local content, or use --force to overwrite.' }
         );
         return;
       }
-      output.warn("Proceeding with push despite truncation (--force flag used)");
     }
-    const pushScope = scope?.toLowerCase() ?? "all";
-    const filteredLocal = filterLocalContent(localContent, pushScope, type);
     output.info("Calculating changes...");
     const diff = calculateDiff(filteredLocal, remoteContent, {
       existingEntries: cliConfig.sync.existingEntries
@@ -7478,7 +7662,7 @@ var formatEntryRow = (entry) => [
   entry.identifier,
   entry.status,
   entry.hasUnpublishedChanges ? "Yes" : "No",
-  entry.slug,
+  entry.slug ?? "-",
   formatDateShort(entry.updatedAt)
 ];
 var upsertCommand = new commander.Command("upsert").description("Create or update an entry").argument("<type>", "Content type").argument("<identifier>", "Entry identifier").option("--data <json>", "Entry data as JSON string").option("--file <path>", "Path to JSON file with entry data").option("--slug <slug>", "Entry slug (defaults to identifier)").option("--title <title>", "Entry title").action(
@@ -7850,9 +8034,9 @@ function resolveOutputMode(options) {
   return "terminal";
 }
 async function writePreviewHtmlFile(html) {
-  const dir = await fs5__namespace.mkdtemp(path9__namespace.join(os__namespace.tmpdir(), "riverbank-preview-"));
+  const dir = await fs3__namespace.mkdtemp(path9__namespace.join(os__namespace.tmpdir(), "riverbank-preview-"));
   const filePath = path9__namespace.join(dir, "index.html");
-  await fs5__namespace.writeFile(filePath, html, "utf-8");
+  await fs3__namespace.writeFile(filePath, html, "utf-8");
   return filePath;
 }
 async function openPreviewFile(filePath) {
@@ -7946,6 +8130,8 @@ function buildSchemaTemplate(state) {
     "",
     "This document captures the content model and SDK configuration for this site.",
     "The generated section is updated by `riverbankcms init-docs`.",
+    "",
+    renderConfigGuideSection(),
     ""
   ].join("\n");
   const generated = buildSchemaGeneratedSection(state);
@@ -8049,6 +8235,132 @@ function renderContentTypesSection(config3) {
   }
   return lines.join("\n");
 }
+function renderConfigGuideSection() {
+  return [
+    "## riverbank.config.ts Guide",
+    "",
+    "Use `riverbank.config.ts` as the source of truth for the site schema, custom blocks, and CLI behavior.",
+    "This section is static guidance for agents; the generated section below shows the live config.",
+    "",
+    "### Field Overrides (blockFieldOptions)",
+    "",
+    "Use `blockFieldOptions` to override the *options* for existing `select` fields.",
+    "This only affects fields that use the `sdkSelect` UI widget (for example: the embed block layout picker).",
+    "",
+    "```ts",
+    "export default defineConfig({",
+    "  siteId: 'your-site-id',",
+    "  blockFieldOptions: {",
+    "    'block.embed': {",
+    "      layout: {",
+    "        options: [",
+    "          { value: 'showcase', label: 'Showcase Grid' },",
+    "          { value: 'list', label: 'Simple List' },",
+    "        ],",
+    "      },",
+    "    },",
+    "    'custom.featured-posts': {",
+    "      style: {",
+    "        options: [",
+    "          { value: 'grid', label: 'Grid' },",
+    "          { value: 'carousel', label: 'Carousel' },",
+    "        ],",
+    "      },",
+    "    },",
+    "  },",
+    "});",
+    "```",
+    "",
+    "### Block Field Extensions (blockFieldExtensions)",
+    "",
+    "Use `blockFieldExtensions` to add *new* fields to built-in system blocks.",
+    "Extended fields appear at the end of the block form and are available via `content` in `blockOverrides`.",
+    "",
+    "```ts",
+    "export default defineConfig({",
+    "  siteId: 'your-site-id',",
+    "  blockFieldExtensions: {",
+    "    'block.hero': {",
+    "      fields: [",
+    "        { id: 'videoBackground', type: 'media', label: 'Video Background', mediaKinds: ['video'] },",
+    "        { id: 'overlayOpacity', type: 'number', label: 'Overlay Opacity', defaultValue: 50 },",
+    "      ],",
+    "    },",
+    "    'block.bodyText': {",
+    "      fields: [",
+    "        { id: 'layout', type: 'select', label: 'Layout', defaultValue: 'default',",
+    "          options: [",
+    "            { value: 'default', label: 'Default' },",
+    "            { value: 'wide', label: 'Wide' },",
+    "          ],",
+    "        },",
+    "      ],",
+    "    },",
+    "  },",
+    "});",
+    "```",
+    "",
+    "Rules:",
+    "- Only system blocks (`block.*`) can be extended.",
+    "- Extended field IDs must not collide with existing block fields.",
+    "- If `required: true`, you must set a `defaultValue` to avoid breaking existing blocks.",
+    "",
+    "### Custom Blocks (customBlocks)",
+    "",
+    "Use `customBlocks` to define new block types with their own fields.",
+    "Custom blocks must be rendered via `blockOverrides` in the SDK site.",
+    "",
+    "```ts",
+    "export default defineConfig({",
+    "  siteId: 'your-site-id',",
+    "  customBlocks: [",
+    "    {",
+    "      id: 'custom.team-member',",
+    "      title: 'Team Member',",
+    "      titleSource: 'name',",
+    "      description: 'Profile card with bio and photo',",
+    "      category: 'content',",
+    "      icon: 'User',",
+    "      fields: [",
+    "        { id: 'name', type: 'text', label: 'Name', required: true },",
+    "        { id: 'role', type: 'text', label: 'Role' },",
+    "        { id: 'photo', type: 'media', label: 'Photo', mediaKinds: ['image'] },",
+    "        { id: 'bio', type: 'richText', label: 'Bio' },",
+    "      ],",
+    "    },",
+    "  ],",
+    "});",
+    "```",
+    "",
+    "### Field Types (for customBlocks and blockFieldExtensions)",
+    "",
+    "All field definitions use the same `FieldDefinition` format as system blocks.",
+    "Supported `type` values:",
+    "",
+    "- `text`: Single or multiline text",
+    "- `richText`: Rich text editor (markdown or HTML)",
+    "- `media`: Image or video upload",
+    "- `boolean`: Toggle/checkbox",
+    "- `number`: Numeric input",
+    "- `date`: Date picker",
+    "- `time`: Time picker",
+    "- `datetime`: Date + time picker",
+    "- `slug`: Slug with optional source field",
+    "- `url`: URL input (optionally allow relative)",
+    "- `link`: Link picker",
+    "- `select`: Single or multi-select options",
+    "- `reference`: Reference another entry type",
+    "- `repeater`: Repeatable list of fields",
+    "- `group`: Group of fields",
+    "- `modal`: Fields inside a modal dialog",
+    "- `tabGroup`: Group fields by tabs",
+    "- `presetOrCustom`: Preset list with custom fallback",
+    "- `contentTypeSelect`: Content type picker (all/routable/nonRoutable)",
+    "- `entryPicker`: Pick a content entry",
+    "",
+    "Tip: For `repeater`, define either `schema.fields` (monomorphic) or `polymorphic: true` with `itemTypes`."
+  ].join("\n");
+}
 function renderCustomBlocksSection(customBlocks) {
   const lines = ["## Custom Blocks", ""];
   if (customBlocks.length === 0) {
@@ -8196,24 +8508,24 @@ async function loadConfig(configPath, output) {
   }
 }
 async function ensureDir2(dirPath) {
-  await fs5__namespace.mkdir(dirPath, { recursive: true });
+  await fs3__namespace.mkdir(dirPath, { recursive: true });
 }
 async function writeFileIfMissing(filePath, contents) {
   try {
-    await fs5__namespace.access(filePath);
+    await fs3__namespace.access(filePath);
   } catch {
-    await fs5__namespace.writeFile(filePath, contents, "utf-8");
+    await fs3__namespace.writeFile(filePath, contents, "utf-8");
   }
 }
 async function upsertGeneratedDoc(filePath, template, generatedSection) {
   const markers = getGeneratedMarkers();
   const contents = await readFileOrTemplate(filePath, template);
   const updated = replaceMarkedSection(contents, markers.start, markers.end, generatedSection);
-  await fs5__namespace.writeFile(filePath, updated, "utf-8");
+  await fs3__namespace.writeFile(filePath, updated, "utf-8");
 }
 async function readFileOrTemplate(filePath, template) {
   try {
-    return await fs5__namespace.readFile(filePath, "utf-8");
+    return await fs3__namespace.readFile(filePath, "utf-8");
   } catch {
     return template;
   }
@@ -8240,7 +8552,7 @@ async function upsertAgentsSection(filePath) {
   const content = await readFileOrTemplate(filePath, "# AGENTS.md\n");
   const section2 = agentsSectionTemplate();
   const updated = replaceMarkedSection(content, AGENTS_START, AGENTS_END, section2);
-  await fs5__namespace.writeFile(filePath, updated, "utf-8");
+  await fs3__namespace.writeFile(filePath, updated, "utf-8");
 }
 function cliReferenceTemplate() {
   return [
@@ -8350,6 +8662,51 @@ var initDocsCommand = new commander.Command("init-docs").description("Scaffold a
     await runInitDocs(options, command);
   })
 );
+var backfillCommand = new commander.Command("backfill").description("Backfill identifiers for pages, blocks, and entries that don't have one").addHelpText("after", `
+This command generates stable identifiers for content created before the SDK was available.
+Identifiers are generated from titles (slugified) and are idempotent - running this
+command multiple times won't overwrite existing identifiers.
+
+Examples:
+  $ riverbankcms identifiers backfill
+  $ riverbankcms identifiers backfill --remote
+`).action(
+  withErrorHandling(async (_options, command) => {
+    const { output, client } = createCommandContext(command);
+    output.info("Backfilling identifiers for pages, blocks, and entries...");
+    const result = await client.identifiers.backfill();
+    const totalUpdated = result.pages.pagesUpdated + result.blocks.total + result.entries.entriesUpdated;
+    if (totalUpdated === 0) {
+      output.success("All content already has identifiers - nothing to backfill");
+      return;
+    }
+    output.success("Backfill complete", {
+      pages: {
+        updated: result.pages.pagesUpdated,
+        identifiers: result.pages.identifiersAssigned
+      },
+      blocks: {
+        updated: result.blocks.total,
+        byPage: Object.keys(result.blocks.byPage).length > 0 ? result.blocks.byPage : void 0
+      },
+      entries: {
+        updated: result.entries.entriesUpdated,
+        identifiers: result.entries.identifiersAssigned
+      }
+    });
+  })
+);
+var identifiersCommand = new commander.Command("identifiers").description("Manage SDK identifiers").addHelpText("after", `
+Identifiers are stable, human-readable names used to reference content in the SDK.
+They are automatically generated when content is created via the SDK, but older
+content may need backfilling.
+
+Commands:
+  backfill    Generate identifiers for content that doesn't have one
+
+Examples:
+  $ riverbankcms identifiers backfill
+`).addCommand(backfillCommand);
 
 // src/cli/index.ts
 dotenv.config({ path: ".env.local" });
@@ -8387,6 +8744,7 @@ program.addCommand(navigationCommand);
 program.addCommand(deleteCommand);
 program.addCommand(previewCommand);
 program.addCommand(initDocsCommand);
+program.addCommand(identifiersCommand);
 program.parse();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map