@bettercms-ai/convert 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -698,7 +698,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 = 3;
+declare const HELPER_VERSION = 4;
 /** 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. */
@@ -979,6 +979,15 @@ interface ComponentizePlanSection {
         componentId?: string;
         proposedSlug?: string;
     };
+    /**
+     * WHERE THIS PLACEMENT'S COPY LIVES — Phase B's one new field.
+     *
+     * `"instance"` says the server moved the group's values onto the instance's `overrides`, so the
+     * placement carries no `bind` and its elements declare the BLOCK lane. ABSENT MEANS `"bind"`:
+     * a plan written by a Phase A server says nothing here, and a codemod that required the field
+     * would refuse every plan older than itself. @see readPlan
+     */
+    copy?: string;
     /** The SERVER already decided it cannot place this one. Not this codemod's to extract. */
     pending?: {
         reason?: string;
@@ -1024,10 +1033,21 @@ interface ComponentizePlan {
  *   `DIALECT_UNSUPPORTED`        the page is svelte / vue / html; nothing is written for it.
  *   `HELPER_CONFLICT`            `src/bcms-content.ts` is a module this package did not write.
  *   `SNAPSHOT_INVALID`           `bcms-content/<page>.json` is not JSON this can add `blocks` to.
+ *   `COPY_MODE_MISMATCH`         `--copy instance` was asked of a plan whose placements are all
+ *                                still bound to page field groups. @see ComponentizeOptions
+ *   `PROP_MAP_INCONSISTENT`      the plan's `fields[].path` is not `<one prefix> + fields[].key`,
+ *                                so a page path cannot be turned into a prop key losslessly.
+ *   `DUPLICATE_FIELD_BINDING`    one element in the section carries more than one
+ *                                `data-bcms-field`, and there is no single address to rewrite.
+ *   `INLINE_NEEDS_INSTANCE`      the page cannot be looped, and the in-place call site the codemod
+ *                                would write carries no `blockId`/`overrides` — so a placement
+ *                                whose copy has MOVED could neither render nor address it.
+ *   `SECTION_UNMIGRATABLE`       an OLDER generated component at this section's path cannot be
+ *                                upgraded to the current format. @see migrateSections
  *   `NOT_IN_SOURCE`              no file we were given renders the group, or the route names no
  *                                page file this package can find.
  */
-type SectionPendingReason = "SECTION_ROOT_AMBIGUOUS" | "SECTION_NOT_CONTIGUOUS" | "SECTION_FREE_IDENTIFIERS" | "COMPONENT_CONFLICT" | "REGISTRY_CONFLICT" | "REGISTRY_UNREADABLE" | "ROUTE_FILE_AMBIGUOUS" | "DIALECT_UNSUPPORTED" | "HELPER_CONFLICT" | "SNAPSHOT_INVALID" | "NOT_IN_SOURCE";
+type SectionPendingReason = "SECTION_ROOT_AMBIGUOUS" | "SECTION_NOT_CONTIGUOUS" | "SECTION_FREE_IDENTIFIERS" | "COMPONENT_CONFLICT" | "REGISTRY_CONFLICT" | "REGISTRY_UNREADABLE" | "ROUTE_FILE_AMBIGUOUS" | "DIALECT_UNSUPPORTED" | "HELPER_CONFLICT" | "SNAPSHOT_INVALID" | "COPY_MODE_MISMATCH" | "PROP_MAP_INCONSISTENT" | "DUPLICATE_FIELD_BINDING" | "INLINE_NEEDS_INSTANCE" | "SECTION_UNMIGRATABLE" | "NOT_IN_SOURCE";
 interface PendingSection {
     route: string;
     groupKey: string;
@@ -1070,6 +1090,15 @@ interface SectionsReceipt {
 interface ComponentizeReceipt {
     /** The plan this run was made against, carried so a receipt can be matched to one. */
     planDigest: string;
+    /**
+     * Which copy model this run was asked for — the same word the server's receipt carries.
+     *
+     * It does NOT change the bytes of an extracted component: the lane an element declares is
+     * decided at render time from the placement's own props, so one file serves both. What it
+     * changes is what the run will accept — `"instance"` against a plan that moved no copy is
+     * `COPY_MODE_MISMATCH` — and what the registry's shipped fallback binds. @see bcmsFields
+     */
+    copy: "bind" | "instance";
     sections: SectionsReceipt;
     /** The component slugs this run wrote a file for, sorted. */
     components: string[];
@@ -1106,9 +1135,27 @@ declare function assertSections(total: number, sections: SectionsReceipt): Secti
 interface ComponentizeOptions {
     /** Replace a helper module this package did not write, instead of refusing. The CLI's flag. */
     overwriteHelper?: boolean;
+    /**
+     * WHICH COPY MODEL THE OPERATOR MEANT — `"bind"` (Phase A, the default) or `"instance"`.
+     *
+     * 🔴 AN ASSERTION, NOT A SWITCH. The extracted files are identical either way, so this flag
+     * exists to catch the order-of-operations mistake that would otherwise be silent: running
+     * `--copy instance` in the repository BEFORE the server has moved the copy leaves a tree that
+     * looks converted and renders every section out of page fields the dashboard is about to hide.
+     * A plan whose placements are all still bound says so, and the run refuses by name.
+     */
+    copy?: "bind" | "instance";
 }
-/** The marker that says a file is OURS. Idempotence is decided on it, never on a path. */
-declare const SECTION_MARKER = "// @bettercms-ai/convert section v1";
+/**
+ * The marker that says a file is OURS — and WHICH FORMAT it is in.
+ *
+ * 🔴 THE VERSION IS LOAD-BEARING, NOT DECORATION. Idempotence is decided on this marker, so a v1
+ * component (0.3: page-path bindings, no render-time lane) read as "already ours, nothing to do"
+ * was skipped forever — every repository converted before Phase B stayed on the page lane, and
+ * `--copy instance` there reported five sections done and moved no address at all. A format change
+ * bumps the version, and anything older is MIGRATED before it is called done. @see migrateSections
+ */
+declare const SECTION_MARKER = "// @bettercms-ai/convert section v2";
 /** The same, for the two modules that hold the registry rather than a section. */
 declare const REGISTRY_MARKER = "// @bettercms-ai/convert sections v1";
 /** Where the generated components live. Fixed, so a second run knows its own output on sight. */