wp-migrate-core 0.1.0-demo → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.1] - 2026-09-03
+
+This release makes inspection safer when an export or output path is not quite what the CLI expects.
+
+- Writes the inspection plan and repair report as one staged handoff, then moves them into place together.
+- Refuses an existing inspection output path without changing its files.
+- Skips missing, invalid, and duplicate WordPress post IDs and explains each skipped item in the repair queue.
+- Keeps malformed numeric XML entities intact instead of letting them crash WXR parsing.
+- Adds regression coverage for the parser edge cases and the CLI's no-clobber behavior.
+
+## [0.1.0-demo] - 2026-09-02
+
+The first public demo: inspect a WordPress WXR export, surface unsupported migration work, and generate a deliberately private Astro handoff for human review.
+
+[0.1.1]: https://github.com/lame13/wp-migrate-core/compare/v0.1.0-demo...v0.1.1
+[0.1.0-demo]: https://github.com/lame13/wp-migrate-core/releases/tag/v0.1.0-demo

package/README.md

@@ -1,6 +1,6 @@
 # wp-migrate-core
 
-`wp-migrate-core` is an intentionally limited, local CLI prototype for inspecting a WordPress WXR export and creating an Astro migration handoff. Version `0.1.0-demo` is published under npm's `demo` tag.
+`wp-migrate-core` is an intentionally limited, local CLI prototype for inspecting a WordPress WXR export and creating an Astro migration handoff. Version `0.1.1` uses npm's `demo` tag.
 
 It can help expose what must be rebuilt. It does not produce a finished or production-ready WordPress replacement.
 
@@ -29,9 +29,9 @@ wp-migrate-core report <export.xml> [--out migration-report.html]
 wp-migrate-core demo [--out wp-migrate-core-demo]
 ```
 
-`inspect` writes `migration-plan.json` and a local repair report. `convert` writes an Astro-shaped project plus its migration manifest and repair report. `report` writes only the repair report. `demo` runs both inspection and conversion against the bundled fixture.
+`inspect` validates the WXR file before writing. It creates `migration-plan.json` and a local repair report as a pair in a new output directory: if either output cannot be created, it leaves neither newly created file behind and never overwrites an existing `--out` path. `convert` writes an Astro-shaped project plus its migration manifest and repair report. `report` writes only the repair report. `demo` runs both inspection and conversion against the bundled fixture.
 
-The `astro` target is the only enabled target in `0.1.0-demo`. `next` and `nuxt` are registered as planned targets and deliberately fail when selected.
+The `astro` target is the only enabled target. `next` and `nuxt` are registered as planned targets and deliberately fail when selected.
 
 ## What the demo handles
 
@@ -40,6 +40,7 @@ The `astro` target is the only enabled target in `0.1.0-demo`. `next` and `nuxt`
 - A bounded subset of serialized Gutenberg core blocks.
 - Elementor `_elementor_data` in WXR post metadata, including simple containers, headings, text, images, buttons, dividers, and spacers.
 - An explicit repair queue for dynamic Gutenberg blocks, unsupported shortcodes, Elementor forms and queries, and unknown Elementor widgets.
+- Items with missing, invalid, or duplicate `wp:post_id` values are skipped and added to the repair report. Correct the export before relying on the handoff.
 
 Each detected construct is marked as `native`, `legacy-html`, `manual`, or `blocked`. Unsupported behavior stays visible in the generated output and repair queue; it is not counted as a successful conversion.
 

package/dist/src/adapters.js

@@ -6,6 +6,6 @@ export const targetAvailability = {
 export function assertTargetEnabled(target) {
     const availability = targetAvailability[target];
     if (!availability.enabled) {
-        throw new Error(`${availability.label} is planned but disabled in 0.1.0-demo. Use --target astro.`);
+        throw new Error(`${availability.label} is planned but not available in this release. Use --target astro.`);
     }
 }

package/dist/src/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { lstat, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assertTargetEnabled, targetAvailability } from "./adapters.js";
 import { parseWxr } from "./core.js";
 import { generateAstroProject } from "./generate.js";
 import { writeReport } from "./report.js";
 function usage() {
-    return `WP Migrate Core 0.1.0-demo
+    return `WP Migrate Core 0.1.1
 
 Usage:
   wp-migrate-core inspect <export.xml> [--out migration-plan] [--target astro]
@@ -16,9 +16,9 @@ Usage:
   wp-migrate-core demo [--out wp-migrate-core-demo]
 
 Targets:
-  astro  implemented in 0.1.0-demo
-  next   not implemented in 0.1.0-demo
-  nuxt   not implemented in 0.1.0-demo
+  astro  implemented
+  next   planned, not implemented
+  nuxt   planned, not implemented
 
 This is a deliberately incomplete demonstration. It does not modify WordPress.`;
 }
@@ -131,20 +131,11 @@ function isNodeErrorCode(error, code) {
     return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 function outputExistsError(outputPath) {
-    return new Error(`Refusing to overwrite existing output: ${outputPath}. Choose a different --out path or remove the existing file intentionally.`);
+    return new Error(`Refusing to overwrite existing output: ${outputPath}. Choose a different --out path or remove the existing path intentionally.`);
 }
-async function ensureInspectionDirectory(directory) {
-    try {
-        const details = await stat(directory);
-        if (!details.isDirectory()) {
-            throw new Error(`Inspect output path exists and is not a directory: ${directory}`);
-        }
-    }
-    catch (error) {
-        if (!isNodeErrorCode(error, "ENOENT"))
-            throw error;
-        await mkdir(directory, { recursive: true });
-    }
+async function prepareInspectionOutput(directory) {
+    await mkdir(dirname(directory), { recursive: true });
+    await assertOutputDoesNotExist(directory);
 }
 async function assertOutputDoesNotExist(outputPath) {
     try {
@@ -186,13 +177,23 @@ function printSummary(project) {
 }
 async function inspect(project, outputDirectory) {
     const directory = resolve(outputDirectory);
+    await prepareInspectionOutput(directory);
+    // A sibling keeps the final rename on the same filesystem.
+    const stagingDirectory = await mkdtemp(resolve(dirname(directory), `.${basename(directory)}.staging-`));
+    try {
+        const stagingPlanPath = resolve(stagingDirectory, "migration-plan.json");
+        const stagingReportPath = resolve(stagingDirectory, "report.html");
+        await writeNewFile(stagingPlanPath, `${JSON.stringify(createMigrationPlan(project), null, 2)}\n`);
+        await writeReport(project, stagingReportPath, { noClobber: true });
+        await assertOutputDoesNotExist(directory);
+        await rename(stagingDirectory, directory);
+    }
+    catch (error) {
+        await rm(stagingDirectory, { recursive: true, force: true });
+        throw error;
+    }
     const planPath = resolve(directory, "migration-plan.json");
     const reportPath = resolve(directory, "report.html");
-    await ensureInspectionDirectory(directory);
-    await assertOutputDoesNotExist(planPath);
-    await assertOutputDoesNotExist(reportPath);
-    await writeNewFile(planPath, `${JSON.stringify(createMigrationPlan(project), null, 2)}\n`);
-    await writeReport(project, reportPath, { noClobber: true });
     printSummary(project);
     console.log(`\nPlan: ${planPath}`);
     console.log(`Report: ${reportPath}`);

package/dist/src/core.d.ts

@@ -3,7 +3,7 @@ import type { InspectOptions, MigrationProject } from "./types.js";
  * Parse a bounded WXR export into a target-neutral migration model.
  *
  * This deliberately does not claim to be a complete XML or WordPress parser. It
- * is dependency-free so 0.1.0-demo can make the conversion boundary visible.
+ * is dependency-free so the conversion boundary stays visible.
  */
 export declare function parseWxr(xml: string, options?: InspectOptions): MigrationProject;
 export declare const inspectWxr: typeof parseWxr;

package/dist/src/core.js

@@ -82,11 +82,12 @@ const SAFE_ELEMENTOR_HREF_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
  * Parse a bounded WXR export into a target-neutral migration model.
  *
  * This deliberately does not claim to be a complete XML or WordPress parser. It
- * is dependency-free so 0.1.0-demo can make the conversion boundary visible.
+ * is dependency-free so the conversion boundary stays visible.
  */
 export function parseWxr(xml, options = {}) {
     const records = [];
     const projectIssues = [];
+    const seenWordPressIds = new Set();
     const channelHeader = xml.slice(0, xml.search(/<item\b/i) === -1 ? xml.length : xml.search(/<item\b/i));
     const itemPattern = /<item\b[^>]*>([\s\S]*?)<\/item>/gi;
     let itemMatch;
@@ -101,19 +102,37 @@ export function parseWxr(xml, options = {}) {
             continue;
         }
         const rawId = cleanField(readTag(itemXml, "wp:post_id"));
-        const wordpressId = Number.parseInt(rawId, 10);
-        if (!Number.isFinite(wordpressId)) {
+        const wordpressId = parseWordPressId(rawId);
+        if (wordpressId === undefined) {
+            const missingId = rawId === "";
             projectIssues.push({
-                id: `project:WXR_ITEM_MISSING_ID:${projectIssues.length + 1}`,
+                id: `project:${missingId ? "WXR_ITEM_MISSING_ID" : "WXR_ITEM_INVALID_ID"}:${projectIssues.length + 1}`,
                 severity: "warning",
-                code: "WXR_ITEM_MISSING_ID",
+                code: missingId ? "WXR_ITEM_MISSING_ID" : "WXR_ITEM_INVALID_ID",
                 sourceId: "wp:unknown",
-                title: "WordPress item is missing its ID",
-                message: `Skipped a ${postType} without a numeric wp:post_id.`,
-                requiredAction: "Inspect the WXR export and restore the missing post identifier."
+                title: missingId ? "WordPress item is missing its ID" : "WordPress item has an invalid ID",
+                message: missingId
+                    ? `Skipped a ${postType} without a wp:post_id.`
+                    : `Skipped a ${postType} because wp:post_id must be a positive integer.`,
+                requiredAction: missingId
+                    ? "Inspect the WXR export and restore the missing post identifier."
+                    : "Inspect the WXR export and restore a positive integer post identifier."
             });
             continue;
         }
+        if (seenWordPressIds.has(wordpressId)) {
+            projectIssues.push({
+                id: `project:WXR_ITEM_DUPLICATE_ID:${projectIssues.length + 1}`,
+                severity: "warning",
+                code: "WXR_ITEM_DUPLICATE_ID",
+                sourceId: `wp:${postType}:${wordpressId}`,
+                title: "WordPress item repeats an existing ID",
+                message: `Skipped a duplicate ${postType} with wp:post_id ${wordpressId}.`,
+                requiredAction: "Inspect the WXR export and resolve the duplicate post identifier before migration."
+            });
+            continue;
+        }
+        seenWordPressIds.add(wordpressId);
         records.push(parseItem(itemXml, postType, status, wordpressId));
     }
     if (records.length === 0) {
@@ -330,7 +349,7 @@ function convertElementorElement(value, sourceId, collector, nextOrdinal) {
         return [node];
     }
     const node = createMutableNode(nodeId, "elementor", widgetType, "unknown", "manual", settings, children);
-    collector.add("warning", "ELEMENTOR_WIDGET_UNKNOWN", `Elementor widget ${widgetType} has no 0.1.0-demo adapter.`, "Replace it with an Astro component or preserve its rendered HTML.", { nodeId, evidence: widgetType });
+    collector.add("warning", "ELEMENTOR_WIDGET_UNKNOWN", `Elementor widget ${widgetType} has no supported adapter in this release.`, "Replace it with an Astro component or preserve its rendered HTML.", { nodeId, evidence: widgetType });
     return [node];
 }
 function scanShortcodes(content, sourceId, collector) {
@@ -376,7 +395,7 @@ function reportGutenbergCompatibility(node, collector) {
         return;
     }
     if (!NATIVE_GUTENBERG_BLOCKS.has(node.sourceType)) {
-        collector.add("warning", "GUTENBERG_UNKNOWN_BLOCK", `Gutenberg block ${node.sourceType} has no 0.1.0-demo adapter.`, "Add an adapter or preserve the block's rendered HTML.", { nodeId: node.id, evidence: node.sourceType });
+        collector.add("warning", "GUTENBERG_UNKNOWN_BLOCK", `Gutenberg block ${node.sourceType} has no supported adapter in this release.`, "Add an adapter or preserve the block's rendered HTML.", { nodeId: node.id, evidence: node.sourceType });
     }
 }
 function parseBlockAttributes(serialized, blockName, nodeId, collector) {
@@ -506,16 +525,36 @@ function cleanOptionalField(value) {
     const cleaned = cleanField(value);
     return cleaned === "" ? undefined : cleaned;
 }
+function parseWordPressId(value) {
+    if (!/^[0-9]+$/.test(value)) {
+        return undefined;
+    }
+    const wordpressId = Number(value);
+    return Number.isSafeInteger(wordpressId) && wordpressId > 0 ? wordpressId : undefined;
+}
 function decodeXmlEntities(value) {
     return value
         .replace(/&lt;/g, "<")
         .replace(/&gt;/g, ">")
         .replace(/&quot;/g, '"')
         .replace(/&apos;/g, "'")
-        .replace(/&#(\d+);/g, (_match, decimal) => String.fromCodePoint(Number.parseInt(decimal, 10)))
-        .replace(/&#x([0-9a-f]+);/gi, (_match, hexadecimal) => String.fromCodePoint(Number.parseInt(hexadecimal, 16)))
+        .replace(/&#(\d+);/g, (entity, decimal) => decodeNumericXmlEntity(entity, decimal, 10))
+        .replace(/&#x([0-9a-f]+);/gi, (entity, hexadecimal) => decodeNumericXmlEntity(entity, hexadecimal, 16))
         .replace(/&amp;/g, "&");
 }
+function decodeNumericXmlEntity(entity, value, radix) {
+    const codePoint = Number.parseInt(value, radix);
+    return isValidXmlCodePoint(codePoint) ? String.fromCodePoint(codePoint) : entity;
+}
+function isValidXmlCodePoint(value) {
+    return (Number.isSafeInteger(value) &&
+        (value === 0x9 ||
+            value === 0xa ||
+            value === 0xd ||
+            (value >= 0x20 && value <= 0xd7ff) ||
+            (value >= 0xe000 && value <= 0xfffd) ||
+            (value >= 0x10000 && value <= 0x10ffff)));
+}
 function htmlToText(value) {
     return decodeXmlEntities(value.replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
 }

package/dist/src/generate.js

@@ -1,7 +1,7 @@
 import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, parse, resolve } from "node:path";
 const GENERATOR_NAME = "wp-migrate-core";
-const GENERATOR_VERSION = "0.1.0-demo";
+const GENERATOR_VERSION = "0.1.1";
 const SAFE_ELEMENTOR_HREF_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
 export async function generateAstroProject(project, outDir) {
     const outputDirectory = await prepareOutputDirectory(outDir);
@@ -293,7 +293,7 @@ npm run dev
 
 Generated content lives in \`src/content/pages\` and \`src/content/posts\`. Route mappings and source IDs live in \`migration/manifest.json\`.
 
-Astro is the only enabled renderer in 0.1.0-demo. Next.js and Nuxt appear in the migration manifest as planned, disabled targets; this output contains no fake compatibility layer for either framework.
+Astro is the only enabled renderer in this handoff. Next.js and Nuxt appear in the migration manifest as planned, disabled targets; this output contains no fake compatibility layer for either framework.
 `;
 }
 function renderContentRecord(generated) {

package/dist/src/report.js

@@ -86,7 +86,7 @@ function renderTargetCard(project, target) {
         <span class="target-state target-state--${enabled ? "available" : "unavailable"}">${state}</span>
       </div>
       <p>${escapeHtml(targetDescriptions[target])}</p>
-      ${enabled ? "" : '<span class="target-card__notice">Not implemented in 0.1.0-demo</span>'}
+      ${enabled ? "" : '<span class="target-card__notice">Not implemented in this release</span>'}
     </article>`;
 }
 function renderSourceBreakdown(project) {
@@ -646,7 +646,7 @@ export function renderReport(project) {
   <header class="topbar">
     <div class="topbar__inner">
       <div class="product">WP Migrate Core</div>
-      <div class="report-meta">Local migration report · Version 0.1.0-demo</div>
+      <div class="report-meta">Local migration report · Version 0.1.1</div>
     </div>
   </header>
 

package/dist/src/types.d.ts

@@ -16,7 +16,7 @@ export interface MigrationNode {
     readonly rawHtml?: string;
 }
 export type MigrationIssueSeverity = "warning" | "blocker";
-export type MigrationIssueCode = "WXR_NO_ITEMS" | "WXR_ITEM_MISSING_ID" | "GUTENBERG_UNCLOSED_BLOCK" | "GUTENBERG_UNMATCHED_CLOSE" | "GUTENBERG_INVALID_ATTRIBUTES" | "GUTENBERG_DYNAMIC_BLOCK" | "GUTENBERG_MEDIA_UNSUPPORTED" | "GUTENBERG_UNKNOWN_BLOCK" | "SHORTCODE_UNSUPPORTED" | "ELEMENTOR_INVALID_DATA" | "ELEMENTOR_FORM_UNSUPPORTED" | "ELEMENTOR_QUERY_UNSUPPORTED" | "ELEMENTOR_IMAGE_REMOTE_MEDIA" | "ELEMENTOR_BUTTON_UNSAFE_URL" | "ELEMENTOR_WIDGET_UNKNOWN";
+export type MigrationIssueCode = "WXR_NO_ITEMS" | "WXR_ITEM_MISSING_ID" | "WXR_ITEM_INVALID_ID" | "WXR_ITEM_DUPLICATE_ID" | "GUTENBERG_UNCLOSED_BLOCK" | "GUTENBERG_UNMATCHED_CLOSE" | "GUTENBERG_INVALID_ATTRIBUTES" | "GUTENBERG_DYNAMIC_BLOCK" | "GUTENBERG_MEDIA_UNSUPPORTED" | "GUTENBERG_UNKNOWN_BLOCK" | "SHORTCODE_UNSUPPORTED" | "ELEMENTOR_INVALID_DATA" | "ELEMENTOR_FORM_UNSUPPORTED" | "ELEMENTOR_QUERY_UNSUPPORTED" | "ELEMENTOR_IMAGE_REMOTE_MEDIA" | "ELEMENTOR_BUTTON_UNSAFE_URL" | "ELEMENTOR_WIDGET_UNKNOWN";
 export interface MigrationIssue {
     readonly id: string;
     readonly severity: MigrationIssueSeverity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wp-migrate-core",
-  "version": "0.1.0-demo",
+  "version": "0.1.1",
   "description": "Turn a WordPress WXR export into an Astro handoff, with a repair queue for the parts that still need a human.",
   "keywords": [
     "wordpress",
@@ -25,6 +25,7 @@
     "wp-migrate-core": "dist/src/cli.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist/src",
     "fixtures/demo-wordpress.xml"
   ],