@contentrain/wp-import 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @contentrain/wp-import
+
+WordPress importers for the Contentrain migration pipeline — ported from a corpus-measured import chain, not written fresh: the identity formulas, PHP-serialized meta decoding, and reference-resolution passes carried over intact.
+
+```
+WXR file or REST API ──► RawIR (source-faithful, provenance-stamped)
+RawIR ──► .contentrain content store (pure file map) + EntrySourceMap
+RawIR + EntrySourceMap ──► CommentsExport (live-service intake payload)
+```
+
+## Usage
+
+```ts
+import { parseWxr, fetchRestRawIR, rawToContentrain, buildCommentsExport } from '@contentrain/wp-import'
+
+// Highest offline rung: a WXR export file
+const { raw, stats } = await parseWxr(createReadStream('export.xml'))
+
+// Or the REST rungs (public, or Application Password → rest_auth)
+const { raw: viaRest } = await fetchRestRawIR({ origin: 'https://site.example', auth: { user, appPassword } })
+
+// RawIR → .contentrain (pure: returns { files, entry_source_map, report })
+const { files, entry_source_map } = rawToContentrain(raw)
+
+// Comments intake payload for a live comments service
+const commentsExport = buildCommentsExport(raw, entry_source_map)
+```
+
+## Guarantees
+
+- **Provenance on every document** — which access rung produced it (`rest_public` / `rest_auth` / `wxr` / `bridge`); absence at a low rung is information, not an error.
+- **Unresolved references are marked, never dropped** (`resolved` flags, ghost terms joining the pool, dropped-relation counts in the report).
+- **Shared identity formulas** — `hexId('posts:' + slug)` — so WXR and REST imports of the same site agree on every entry id (delta imports depend on this).
+- **UTC dates** — GMT columns preferred, stamped ISO 8601 `Z`.
+- **Pure conversion** — `rawToContentrain` returns a canonical-serialized file map (sorted keys, 2-space indent, trailing newline); writing to disk is the caller's one line.
+- **EntrySourceMap produced at the only place that can know it** — the WP-id → entry-address mapping the comments intake requires.
+
+Streaming WXR parse (sax): a 100 MB export holds only its records in memory.

package/dist/index.d.mts

@@ -0,0 +1,98 @@
+import { CommentsExport, EntrySourceMap, HandoffComments, RawIR } from "@contentrain/types";
+import { Readable } from "node:stream";
+
+//#region src/wxr.d.ts
+interface WxrStats {
+  serialized: {
+    detected: number;
+    decoded: number;
+    failed: number;
+    keys: string[];
+  };
+  acf_fields: number;
+  unresolved_terms: number;
+  counts: Record<string, number>;
+}
+interface WxrParseResult {
+  raw: RawIR;
+  stats: WxrStats;
+}
+declare function parseWxr(input: string | Readable, opts?: {
+  tool?: string;
+}): Promise<WxrParseResult>;
+//#endregion
+//#region src/rest.d.ts
+interface RestImportOptions {
+  origin: string;
+  /** Injectable for tests and for hosts that need custom dispatch. */
+  fetchImpl?: typeof fetch;
+  /** WordPress Application Password credentials — lifts the rung to rest_auth. */
+  auth?: {
+    user: string;
+    appPassword: string;
+  };
+  perPage?: number;
+  tool?: string;
+}
+interface RestImportResult {
+  raw: RawIR;
+  warnings: string[];
+}
+declare function fetchRestRawIR(options: RestImportOptions): Promise<RestImportResult>;
+//#endregion
+//#region src/contentrain.d.ts
+interface ImportReport {
+  slug_rewritten: number;
+  slug_fallback: number;
+  title_fallback: number;
+  meta_fields: Record<string, string>;
+  acf_fields: Record<string, string>;
+  skipped_types: string[];
+  dropped_relations: number;
+  models: Record<string, {
+    kind: string;
+    domain: string;
+    fields: number;
+    entries: number;
+  }>;
+}
+interface ContentrainResult {
+  files: Record<string, string>;
+  entry_source_map: EntrySourceMap;
+  report: ImportReport;
+}
+declare function rawToContentrain(raw: RawIR, opts?: {
+  updatedBy?: string;
+}): ContentrainResult;
+//#endregion
+//#region src/comments.d.ts
+declare function buildCommentsExport(raw: RawIR, entries: EntrySourceMap, opts?: {
+  generated_at?: string;
+}): CommentsExport;
+/** Handoff summary for the export: counts + closed threads + what could not be addressed. */
+declare function summarizeComments(exp: CommentsExport): HandoffComments;
+//#endregion
+//#region src/php-unserialize.d.ts
+interface UnserializeResult {
+  ok: boolean;
+  serialized: boolean;
+  value: unknown;
+  error?: string;
+}
+declare function looksSerialized(s: unknown): s is string;
+declare function phpUnserialize(str: string): unknown;
+/** Attempt a decode; on failure the value stays exactly as it was. */
+declare function tryUnserialize(s: string): UnserializeResult;
+//#endregion
+//#region src/core.d.ts
+declare const strip: (s: unknown) => string;
+/** Entry id: deterministic hex from a stable key (model:slug style). */
+declare const hexId: (s: string) => string;
+/** Canonical serialization: sorted keys, 2-space indent, trailing newline. */
+declare const canon: (o: unknown) => string;
+/** Taxonomy → model id. */
+declare const taxModelId: (t: string) => string;
+declare const slugify: (s: unknown) => string;
+//#endregion
+export { type ContentrainResult, type ImportReport, type RestImportOptions, type RestImportResult, type UnserializeResult, type WxrParseResult, type WxrStats, buildCommentsExport, canon, fetchRestRawIR, hexId, looksSerialized, parseWxr, phpUnserialize, rawToContentrain, slugify, strip, summarizeComments, taxModelId, tryUnserialize };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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"],"mappings":";;;;UA0BiB,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;;;UCrC3E,iBAAA;EACf,MAAA;;EAEA,SAAA,UAAmB,KAAA;EDQI;ECNvB,IAAA;IAAS,IAAA;IAAc,WAAA;EAAA;EACvB,OAAA;EACA,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,EAAK,KAAA;EACL,QAAA;AAAA;AAAA,iBA0BoB,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;;;UC1BzD,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;AAAA;AAAA,UAGxD,iBAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;EAClB,MAAA,EAAQ,YAAA;AAAA;AAAA,iBAWM,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,IAAA;EAAS,SAAA;AAAA,IAAuB,iBAAA;;;iBC5C7D,mBAAA,CAAoB,GAAA,EAAK,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,IAAA;EAAS,YAAA;AAAA,IAA0B,cAAA;AHkB5G;AAAA,iBGHgB,iBAAA,CAAkB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;UCnBvC,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;;cA+BT,UAAA,GAAc,CAAA;AAAA,cAGd,OAAA,GAAW,CAAA"}