@contentrain/wp-import 0.6.0 → 0.8.0

package/README.md

@@ -102,6 +102,108 @@ these before claiming a complete migration. ACF field/group records and their
 cross-model parents remain in the content store; route discovery decides which
 records become public pages. Importing configuration does not execute a plugin.
 
+### Site name over REST
+
+`fetchRestRawIR` reads the `/wp-json/` index for the site's name and tagline
+(`RawIR.site.title` / `description`, the store's `site` singleton) and its
+install and public addresses (`base_site_url` / `base_blog_url`). An index that
+does not answer leaves them out.
+
+### Menus over REST
+
+With an Application Password, `fetchRestRawIR` reads the site's menus into
+`RawIR.menus`: classic menus (`/wp/v2/menus` + `/wp/v2/menu-items`, with the
+theme locations each is assigned to) and a block theme's published
+`wp_navigation` posts (links, submenus, page lists, home links). A block menu's
+`locations` are the template-part areas (`header`, `footer`) whose navigation
+block refers to it; an empty navigation block without a `ref` shows the most
+recent published one, as WordPress does. Block menu items have no WordPress id
+and get negative ids; the store claims no `wp_id` for them.
+
+A navigation block in a template part that carries its own links (an inline
+navigation, as in Twenty Twenty-Five's footer columns) is a menu of that part's
+area: `Footer navigation 1`, `2`, … (its `ariaLabel` names it when set), links
+in order and nested. Only template parts a template uses count — a theme ships
+alternatives (`footer-columns`, `header-large-title`) that no page shows; without
+the templates, the part named after its area (`header`, `footer`). A `#` link
+stays `#`. Inline menus have no WordPress record: negative ids, no `wp_id`.
+
+A menu item that is itself a draft, or whose post target is not proven public
+— a draft, pending, private, scheduled or password-protected post, or one this
+import never read (a type outside REST, a listing past a page cap) — is left
+out, fail-closed: its label is often that post's title. Its children move up to the
+nearest kept ancestor; `warnings` gives only the count.
+
+Both need `edit_theme_options`. Without a credential, with a rejected one, or
+with a user who lacks that right, no menus are read and the result's `gaps`
+contains `menus_require_auth` — an empty menu list is never presented as the
+site having none. The `menus` model gains a `locations` field only when the
+source named them.
+
+### ACF fields, custom post types and taxonomies over REST
+
+ACF / Secure Custom Fields values arrive on a post's `acf` key — only for field
+groups set to "Show in REST API" (off by default). Each field is typed by one
+versioned table (`ACF_MAPPING_VERSION`, exported with `ACF_SCALAR_TYPES` and
+`ACF_REFERENCE_TYPES`): the ACF type is read from SCF's `<name>_source.type`
+where the site states it, and inferred from the value's shape only when nothing
+states it (the field description then says so).
+
+| ACF | Contentrain |
+| --- | --- |
+| text, time picker | `string` |
+| textarea | `text` |
+| wysiwyg | `richtext` |
+| email / url, oembed / number, range / true false | `email` / `url` / `number` / `boolean` |
+| date picker / date time picker | `date` / `datetime` (ISO, with the site's offset) |
+| color picker / icon picker | `color` / `icon` |
+| select, radio, button group | `select` (its choices) |
+| checkbox, multiple select | `array` of `select` |
+| image / file | `image` / `file` (the URL) |
+| link | `object { url, title, target }` |
+| google map | `object { address, lat, lng, zoom }` |
+| group | `object` of its fields |
+| repeater | `array` of `object` (nested repeaters nest) |
+| flexible content | `array` of `object`: a required `layout` select plus the union of the layouts' fields |
+| post object, relationship | `relation` / `relations` to the entries' models |
+| taxonomy / user / gallery | `relations` to the term model / `authors` / media |
+| page link | `url`: the target's address, only when the target is published and unprotected |
+| tab, accordion, message | nothing (layout only) |
+| password | nothing, ever |
+
+Sub-fields of a repeater, group or flexible layout are typed by the same table
+when the site states their type (SCF's `_source` inside each row); a reference
+inside a row, and a sub-field with no stated type, are typed from the value. A
+select or checkbox value outside the field's stated choices is left out and
+counted in the report's `acf_outside_choices`. A date time picker's value is written
+with the site's UTC offset for that moment, DST included (the `/wp-json/`
+index's `timezone_string`, else `gmt_offset`); with neither it stays local and
+`acf_datetime_unzoned` counts it. `src/fixtures/acf-parity.json`
+holds the cases the Contentrain Bridge must map the same way.
+
+**A password field is never read** — at any depth: a password sub-field of a
+repeater row, a group or a flexible layout is removed with its `_source` before
+the value reaches `RawIR`. Where the source states the type, the type decides;
+where it does not (plain ACF, no `<name>_source`), a field whose name has a
+secret word in it (`password`, `user_pass`, `apiKey`, `access_token`, …; whole
+words, so `passage` stays) is skipped instead. It never reaches `RawIR`, the
+store, or a report.
+
+ACF values follow their post: a draft's fields land in the store with the
+draft (meta `status: draft`), like its body. A reference to an entry the import
+did not read is dropped and counted in `dropped_relations`. The report's
+`acf_fields` lists each field's type. When any post carries an `acf` key, the
+result's `gaps` contains `acf_partial`: groups without REST exposure, options
+pages and fields on post types outside REST are not visible to REST — the
+Bridge reads those.
+
+With an Application Password, post types are read with `context=edit` so their
+`viewable` flag is known: a type that is in REST but not publicly queryable (a
+testimonial post type, say) keeps its content but gets no address (`link` is
+null), so no route or redirect claims a page that does not exist. Custom
+taxonomies in REST are read with their terms, and a post's terms in them become
+its relations.
+
 
 ### Publication and translation identity
 

package/dist/index.d.mts

@@ -67,6 +67,15 @@ interface RestImportResult {
     status: 'none' | 'accepted' | 'rejected';
     fell_back: string[];
   };
+  /**
+   * What this rung could not read, as codes a caller can act on (the text is in `warnings`).
+   * `menus_require_auth`: menus and block navigation are only readable with an application password
+   * of a user who may edit theme options — none was given, the site rejected it, or it lacks that right.
+   * `acf_partial`: the site runs ACF / Secure Custom Fields; REST shows only the field groups set to
+   * `show_in_rest` (off by default) and no options page — the Bridge export reads the rest. Where the site
+   * states no field types (plain ACF, no `<name>_source`), a secret field is recognised by its name only.
+   */
+  gaps: string[];
 }
 declare function fetchRestRawIR(options: RestImportOptions): Promise<RestImportResult>;
 //#endregion
@@ -77,6 +86,10 @@ interface ImportReport {
   title_fallback: number;
   meta_fields: Record<string, string>;
   acf_fields: Record<string, string>;
+  /** ACF select/checkbox values outside their field's stated choices, left out (`field: count`). */
+  acf_outside_choices: Record<string, number>;
+  /** ACF date-times written without a zone because the source named none (`timezone_string` / `gmt_offset`). */
+  acf_datetime_unzoned: number;
   skipped_types: string[];
   dropped_relations: number;
   models: Record<string, {
@@ -96,6 +109,11 @@ interface ImportReport {
    * put that text on a public site. Publish only after deciding what to show.
    */
   password_protected_drafts: number;
+  /**
+   * The source named no site title (no REST index name, no WXR channel title): the `site` entry has no
+   * `title`. The field stays required, so the store says what is missing rather than inventing a name.
+   */
+  site_title_missing: boolean;
 }
 interface ContentrainResult {
   files: Record<string, string>;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/wxr.ts","../src/rest.ts","../src/contentrain.ts","../src/comments.ts","../src/php-unserialize.ts","../src/core.ts","../src/delta.ts"],"mappings":";;;;UA2BiB,QAAA;EACf,UAAA;IAAc,QAAA;IAAkB,OAAA;IAAiB,MAAA;IAAgB,IAAA;EAAA;EACjE,UAAA;EACA,gBAAA;EACA,MAAA,EAAQ,MAAA;AAAA;AAAA,UAGO,cAAA;EACf,GAAA,EAAK,KAAA;EACL,KAAA,EAAO,QAAA;AAAA;AAAA,iBAiBa,QAAA,CAAS,KAAA,WAAgB,QAAA,EAAU,IAAA;EAAS,IAAA;AAAA,IAAkB,OAAA,CAAQ,cAAA;;;UCtC3E,iBAAA;EACf,MAAA;;EAEA,SAAA,UAAmB,KAAA;EDSI;;;;;;;;ECAvB,IAAA;IAAS,IAAA;IAAc,WAAA;EAAA;EACvB,OAAA;EDGc;AAGhB;;;;ECAE,WAAA;EDCK;;;;ECIL,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,EAAK,KAAA;EACL,QAAA;EDQkF;;;;;;;;ECClF,UAAA;IAAc,MAAA;IAA0C,SAAA;EAAA;AAAA;AAAA,iBA+CpC,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;;;UC1EzD,YAAA;EACf,cAAA;EACA,aAAA;EACA,cAAA;EACA,WAAA,EAAa,MAAA;EACb,UAAA,EAAY,MAAA;EACZ,aAAA;EACA,iBAAA;EACA,MAAA,EAAQ,MAAA;IAAiB,IAAA;IAAc,MAAA;IAAgB,MAAA;IAAgB,OAAA;EAAA;EFJvE;EEMA,OAAA;EFNc;EEQd,kBAAA;EFLe;;;;;;EEYf,yBAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;EAClB,MAAA,EAAQ,YAAA;AAAA;AAAA,iBAoCM,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,IAAA;EAAS,SAAA;AAAA,IAAuB,iBAAA;;;;;;AF7D7E;;;iBGbgB,cAAA,CAAe,GAAA,EAAK,KAAA;EAAU,QAAA,EAAU,UAAA;EAAc,QAAA,EAAU,WAAA,CAAY,cAAA;AAAA;AAAA,iBAgB5E,mBAAA,CAAoB,GAAA,EAAK,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,IAAA;EAAS,YAAA;AAAA,IAA0B,cAAA;;iBAiB5F,iBAAA,CAAkB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;UC3CvC,iBAAA;EACf,EAAA;EACA,UAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,CAAA,YAAa,CAAA;AAAA,iBAI7B,cAAA,CAAe,GAAA;;iBAyFf,cAAA,CAAe,CAAA,WAAY,iBAAA;;;cC9F9B,KAAA,GAAS,CAAA;;cAST,KAAA,GAAS,CAAA;;cAcT,KAAA,GAAS,CAAA;;;;;;;;;ALCtB;cK8Ba,UAAA,EAAU,MAAA;;cAIV,WAAA,EAAW,MAAA;;cAOX,UAAA,GAAc,CAAA;AAAA,cAGd,OAAA,GAAW,CAAA;;;;UC3DP,UAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;AAAA;AAAA,UAGH,oBAAA;ENOD;EMLd,KAAA,EAAO,eAAA;ENEO;EMAd,KAAA,EAAO,UAAA;ENA0C;EMEjD,QAAA,GAAW,UAAA;ENDX;;;;;EMOA,UAAA;ENFe;;;;EMOf,SAAA;AAAA;AAAA,cAGW,kBAAA;AAAA,cACA,iBAAA;;;ANQb;;;;;;;;;;iBM8NgB,eAAA,CAAgB,KAAA,EAAO,oBAAA,GAAuB,eAAA;;iBAkC9C,uBAAA,CAAwB,IAAA,EAAM,eAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/wxr.ts","../src/rest.ts","../src/contentrain.ts","../src/comments.ts","../src/php-unserialize.ts","../src/core.ts","../src/delta.ts"],"mappings":";;;;UA2BiB,QAAA;EACf,UAAA;IAAc,QAAA;IAAkB,OAAA;IAAiB,MAAA;IAAgB,IAAA;EAAA;EACjE,UAAA;EACA,gBAAA;EACA,MAAA,EAAQ,MAAA;AAAA;AAAA,UAGO,cAAA;EACf,GAAA,EAAK,KAAA;EACL,KAAA,EAAO,QAAA;AAAA;AAAA,iBAiBa,QAAA,CAAS,KAAA,WAAgB,QAAA,EAAU,IAAA;EAAS,IAAA;AAAA,IAAkB,OAAA,CAAQ,cAAA;;;UCpC3E,iBAAA;EACf,MAAA;;EAEA,SAAA,UAAmB,KAAA;EDOI;;;;;;;;ECEvB,IAAA;IAAS,IAAA;IAAc,WAAA;EAAA;EACvB,OAAA;EDCc;AAGhB;;;;ECEE,WAAA;EDDK;;;;ECML,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,EAAK,KAAA;EACL,QAAA;EDMkF;;;;;;;;ECGlF,UAAA;IAAc,MAAA;IAA0C,SAAA;EAAA;;;AAvC1D;;;;;;EAgDE,IAAA;AAAA;AAAA,iBA2EoB,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;;;UChHzD,YAAA;EACf,cAAA;EACA,aAAA;EACA,cAAA;EACA,WAAA,EAAa,MAAA;EACb,UAAA,EAAY,MAAA;EFFE;EEId,mBAAA,EAAqB,MAAA;EFPP;EESd,oBAAA;EACA,aAAA;EACA,iBAAA;EACA,MAAA,EAAQ,MAAA;IAAiB,IAAA;IAAc,MAAA;IAAgB,MAAA;IAAgB,OAAA;EAAA;EFNxD;EEQf,OAAA;;EAEA,kBAAA;EFTA;;;;;;EEgBA,yBAAA;EFE4B;;;;EEG5B,kBAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;EAClB,MAAA,EAAQ,YAAA;AAAA;AAAA,iBA0CM,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,IAAA;EAAS,SAAA;AAAA,IAAuB,iBAAA;;;;;;AF7E7E;;;iBGbgB,cAAA,CAAe,GAAA,EAAK,KAAA;EAAU,QAAA,EAAU,UAAA;EAAc,QAAA,EAAU,WAAA,CAAY,cAAA;AAAA;AAAA,iBAgB5E,mBAAA,CAAoB,GAAA,EAAK,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,IAAA;EAAS,YAAA;AAAA,IAA0B,cAAA;;iBAiB5F,iBAAA,CAAkB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;UC3CvC,iBAAA;EACf,EAAA;EACA,UAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,CAAA,YAAa,CAAA;AAAA,iBAI7B,cAAA,CAAe,GAAA;;iBAyFf,cAAA,CAAe,CAAA,WAAY,iBAAA;;;cC9F9B,KAAA,GAAS,CAAA;;cAST,KAAA,GAAS,CAAA;;cAcT,KAAA,GAAS,CAAA;;;;;;;;;ALCtB;cK8Ba,UAAA,EAAU,MAAA;;cAIV,WAAA,EAAW,MAAA;;cAOX,UAAA,GAAc,CAAA;AAAA,cAGd,OAAA,GAAW,CAAA;;;;UC3DP,UAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;AAAA;AAAA,UAGH,oBAAA;ENOD;EMLd,KAAA,EAAO,eAAA;ENEO;EMAd,KAAA,EAAO,UAAA;ENA0C;EMEjD,QAAA,GAAW,UAAA;ENDX;;;;;EMOA,UAAA;ENFe;;;;EMOf,SAAA;AAAA;AAAA,cAGW,kBAAA;AAAA,cACA,iBAAA;;;ANQb;;;;;;;;;;iBM8NgB,eAAA,CAAgB,KAAA,EAAO,oBAAA,GAAuB,eAAA;;iBAkC9C,uBAAA,CAAwB,IAAA,EAAM,eAAA"}