@bettercms-ai/convert 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -955,7 +955,7 @@ declare function attrsFor(path: string, kind: string, props?: AttrBinding[], sco
 declare function propsAttribute(props: AttrBinding[]): string;
 
 /** Bumped whenever the emitted source changes. `isKnownHelper` upgrades anything older. */
-declare const HELPER_VERSION = 11;
+declare const HELPER_VERSION = 12;
 /** Where each dialect's helper lives. Null = this dialect reads nothing at build time. */
 declare const HELPER_PATH: Record<Dialect, string | null>;
 /** The directory the snapshots live in, at the repository root. */
@@ -981,6 +981,22 @@ declare function helperSource(dialect: Dialect): string;
  * treats them the same way, because it cannot tell them apart and must not overwrite either.
  */
 declare function isKnownHelper(content: string, dialect: Dialect): number | null;
+/** One committed helper a build may replace: where it lives, what replaces it, and which bytes qualify. */
+interface HelperUpgrade {
+    path: string;
+    source: string;
+    /** sha256 of every OLDER helper this package wrote at `path`. Anything else is left alone. */
+    digests: string[];
+}
+/**
+ * What a BetterCMS build swaps in for a helper this package wrote at an older version.
+ *
+ * The hosting builder applies these to its own throwaway checkout — never to the repository — so a
+ * site converted before the helper read published content at request time gets that reader on its
+ * next build, with no commit and no codemod run. The rule is `isKnownHelper`'s: only bytes this
+ * package produced are replaced, so an edited or foreign module at the same path is never touched.
+ */
+declare function helperUpgrades(): HelperUpgrade[];
 
 /**
  * The submit runtime, LIFTED VERBATIM from `src/lib/sites/render-page.ts` `FORM_SCRIPT`.
@@ -1949,4 +1965,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeSections, walkAst, wireForms };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type HelperUpgrade, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, helperUpgrades, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeSections, walkAst, wireForms };

package/dist/index.js

@@ -4187,7 +4187,7 @@ async function bindImages(ctx, targets) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 11;
+var HELPER_VERSION = 12;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -4244,8 +4244,69 @@ function render(value: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * The PUBLISHED copy, on a server BetterCMS hosts \u2014 read at request time, not at build time.
+ *
+ * BetterCMS keeps one file current for a running server app (\`BCMS_CONTENT_FILE\`, the same
+ * bcms-content.json the build was given) and rewrites it on every publish, so a server-rendered
+ * page shows a publish within seconds instead of after a rebuild. Each snapshot this module reads
+ * resolves to its live counterpart: the shared layout by identity, a page by its \`slug\`.
+ *
+ * Nowhere else does anything change: with no variable (a build, \`astro dev\`, a browser, an edge
+ * runtime) every snapshot is the one the bundle imported, exactly as before. A file that cannot be
+ * read keeps the last good copy; it is checked at most once a second.
+ */
+type BcmsLiveContent = { stamp: number; bySlug: Map<string, unknown>; layout: unknown };
+let bcmsLive: BcmsLiveContent | null = null;
+let bcmsLiveCheckedAt = 0;
+
+function liveContent(): BcmsLiveContent | null {
+  const proc = (globalThis as {
+    process?: { env?: Record<string, string | undefined>; getBuiltinModule?: (id: string) => unknown };
+  }).process;
+  const file = proc?.env?.BCMS_CONTENT_FILE;
+  if (!file || typeof proc?.getBuiltinModule !== "function") return null;
+  const now = Date.now();
+  if (now - bcmsLiveCheckedAt < 1000) return bcmsLive;
+  bcmsLiveCheckedAt = now;
+  try {
+    const fs = proc.getBuiltinModule("node:fs") as {
+      statSync(path: string): { mtimeMs: number };
+      readFileSync(path: string, encoding: "utf8"): string;
+    };
+    const stamp = fs.statSync(file).mtimeMs;
+    if (bcmsLive && bcmsLive.stamp === stamp) return bcmsLive;
+    const snapshot: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    const bySlug = new Map<string, unknown>();
+    const collections = isRecord(snapshot) && isRecord(snapshot.collections) ? snapshot.collections : {};
+    for (const rows of Object.values(collections)) {
+      if (!Array.isArray(rows)) continue;
+      for (const row of rows) {
+        if (isRecord(row) && typeof row.slug === "string" && !bySlug.has(row.slug)) bySlug.set(row.slug, row);
+      }
+    }
+    const pages = isRecord(snapshot) && Array.isArray(snapshot.pages) ? snapshot.pages : [];
+    const withLayout = pages.find((page: unknown) => isRecord(page) && isRecord(page.layout));
+    const layout = isRecord(withLayout) ? withLayout.layout : isRecord(snapshot) ? snapshot.layout : undefined;
+    bcmsLive = { stamp, bySlug, layout };
+  } catch {
+    // Unreadable, or caught mid-write: keep serving the last good copy.
+  }
+  return bcmsLive;
+}
+
+/** The published counterpart of a snapshot this module was handed, or the snapshot itself. */
+function live(page: unknown): unknown {
+  const content = liveContent();
+  if (!content) return page;
+  if (page === layoutSnapshot) return isRecord(content.layout) ? content.layout : page;
+  if (isRecord(page) && typeof page.slug === "string") return content.bySlug.get(page.slug) ?? page;
+  return page;
+}
+
 /** One field of one page. \`slug\` selects the entry on a dynamic route. */
 export function bcms(page: unknown, path: string, fallback: string, slug?: string): string {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   return render(readPath(root, path)) ?? fallback;
@@ -4253,7 +4314,7 @@ export function bcms(page: unknown, path: string, fallback: string, slug?: strin
 
 /** One field of the shared layout \u2014 the header and footer every route renders. */
 export function bcmsLayout(path: string, fallback: string): string {
-  return render(readPath(layoutSnapshot, path)) ?? fallback;
+  return render(readPath(live(layoutSnapshot), path)) ?? fallback;
 }
 
 /**
@@ -4261,6 +4322,7 @@ export function bcmsLayout(path: string, fallback: string): string {
  * an empty snapshot still renders the same number of cards it always did.
  */
 export function bcmsRows<T>(page: unknown, path: string, fallback: T[], slug?: string): T[] {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   const value = readPath(root, path);
@@ -4306,6 +4368,7 @@ export function bcmsRowsAs<T>(
  * this out loud rather than leaving an editor to discover it.
  */
 export function bcmsList(page: unknown, paths: string[], fallback: string[], slug?: string): string[] {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   return paths.map((path, index) => render(readPath(root, path)) ?? fallback[index] ?? "");
@@ -4330,6 +4393,7 @@ export function bcmsTuples(page: unknown, paths: string[][], fallback: string[][
  * no such rule and takes the CMS url directly.
  */
 export function bcmsImage<T>(page: unknown, path: string, fallback: T, slug?: string): T | string {
+  page = live(page);
   if (fallback !== null && typeof fallback === "object") return fallback;
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
@@ -4358,6 +4422,7 @@ export function bcmsSection(
   overrides?: unknown,
   bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
+  page = live(page);
   const group = bind ? readPath(page, bind) : undefined;
   const base: Record<string, unknown> = isRecord(group) ? { ...group } : {};
   // A locale copy on its twin's component spells its fields its own way: each prop's copy is
@@ -4429,6 +4494,7 @@ export function bcmsSectionPaths(
   map: BcmsPathMap,
   bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
+  page = live(page);
   const out: Record<string, unknown> = isRecord(page) ? { ...page } : {};
   const own = isRecord(overrides) ? overrides : {};
   const separator = prefix.slice(-1);
@@ -4662,7 +4728,8 @@ var HISTORICAL = {
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
     9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
-    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910",
+    11: "ceb2a932d4c2761a5045ff35032e0b45130a0b5034547ff37579c72c9ce3594e"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
@@ -4674,7 +4741,8 @@ var HISTORICAL = {
     7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7",
     8: "1a6f669d76d42effe77f082436e9d21c0efa6fc499e919e3d116bc3a27a7f3d5",
     9: "eee9fb1635ae7d6f8f33676a1f390600ca24a62ee992775252273c73a011c494",
-    10: "35bb7c0e30f5c41fe68e52259ec4764de6de2734064fa0e1521f3338eef0a09e"
+    10: "35bb7c0e30f5c41fe68e52259ec4764de6de2734064fa0e1521f3338eef0a09e",
+    11: "818784f2088150d64d91b42eac944dc9503f104d32a0e7a18c753d2982a5adc0"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
@@ -4686,7 +4754,8 @@ var HISTORICAL = {
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
     9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
-    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910",
+    11: "ceb2a932d4c2761a5045ff35032e0b45130a0b5034547ff37579c72c9ce3594e"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -4700,6 +4769,15 @@ function isKnownHelper(content, dialect) {
   }
   return null;
 }
+function helperUpgrades() {
+  const out = /* @__PURE__ */ new Map();
+  for (const dialect of Object.keys(HELPER_PATH)) {
+    const path = HELPER_PATH[dialect];
+    if (!path || out.has(path)) continue;
+    out.set(path, { path, source: helperSource(dialect), digests: Object.values(HISTORICAL[path] ?? {}) });
+  }
+  return [...out.values()];
+}
 
 // src/locate.ts
 var flat = (value) => value.replace(/\s+/g, " ").trim();
@@ -10719,6 +10797,7 @@ export {
   fixFor,
   flat,
   helperSource,
+  helperUpgrades,
   importsIn,
   isDecorativeGlyph,
   isDynamicRoute,