wp-migrate-core 0.1.0-demo

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wp-migrate-core contributors
+
+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,74 @@
+# 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.
+
+It can help expose what must be rebuilt. It does not produce a finished or production-ready WordPress replacement.
+
+## Install
+
+Requires Node.js 20 or later.
+
+```bash
+npm install --save-dev wp-migrate-core@demo
+```
+
+Run the included fictional fixture:
+
+```bash
+npx wp-migrate-core demo --out wp-migrate-core-demo
+```
+
+The demo writes a migration plan, a local HTML repair report, and an Astro-shaped project to `wp-migrate-core-demo/`. Open `wp-migrate-core-demo/migration-plan/report.html` locally to review the detected work.
+
+## Commands
+
+```text
+wp-migrate-core inspect <export.xml> [--out migration-plan] [--target astro]
+wp-migrate-core convert <export.xml> --out <new-site> [--target astro]
+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.
+
+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.
+
+## What the demo handles
+
+- Published WordPress pages and posts in a WXR export.
+- Routes, authors, dates, taxonomies, source IDs, and post metadata in the migration model.
+- 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.
+
+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.
+
+## Important limits
+
+This package does not perform live-site extraction, authenticate with WordPress, download media, rewrite media URLs, reproduce themes or responsive layouts, compare the generated site visually or behaviorally with the source, or migrate plugin behavior such as forms, search, comments, memberships, or ecommerce.
+
+Before treating an output as a handoff, review every blocker and warning; then verify routes, content, media, forms, dynamic behavior, metadata, accessibility, and visual behavior against the source site. Generated output is a starting point for deliberate engineering work, not a deployment artifact.
+
+## Privacy and local handoff
+
+The CLI reads the WXR file you provide and writes generated content to your local filesystem. It does not modify WordPress. A WXR export and the resulting migration plan, report, and generated project can contain private content, author names, source URLs, raw HTML, and post metadata.
+
+Run it in a trusted local working directory. Treat the input and every generated output as potentially confidential: review and remove sensitive material before committing, uploading, sharing, or deploying it. The default generated directories are ignored by this repository, but that does not make their contents safe to share.
+
+## Demo fixture
+
+`fixtures/demo-wordpress.xml` contains fictional data only. Bright Path Plumbing, its author name, URLs under `brightpath.example`, and the fixture's page and post content exist solely to demonstrate the migration flow.
+
+## Development
+
+From a checkout:
+
+```bash
+npm install
+npm test
+npm run demo
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/src/adapters.d.ts

@@ -0,0 +1,25 @@
+import type { MigrationProject, OutputTarget } from "./types.js";
+export interface TargetAdapter {
+    readonly target: OutputTarget;
+    readonly enabled: boolean;
+    readonly label: string;
+    generate(project: MigrationProject, outputDirectory: string): Promise<void>;
+}
+export declare const targetAvailability: {
+    readonly astro: {
+        readonly target: "astro";
+        readonly label: "Astro";
+        readonly enabled: true;
+    };
+    readonly next: {
+        readonly target: "next";
+        readonly label: "Next.js";
+        readonly enabled: false;
+    };
+    readonly nuxt: {
+        readonly target: "nuxt";
+        readonly label: "Nuxt";
+        readonly enabled: false;
+    };
+};
+export declare function assertTargetEnabled(target: OutputTarget): void;

package/dist/src/adapters.js

@@ -0,0 +1,11 @@
+export const targetAvailability = {
+    astro: { target: "astro", label: "Astro", enabled: true },
+    next: { target: "next", label: "Next.js", enabled: false },
+    nuxt: { target: "nuxt", label: "Nuxt", enabled: false }
+};
+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.`);
+    }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { lstat, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { 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
+
+Usage:
+  wp-migrate-core inspect <export.xml> [--out migration-plan] [--target astro]
+  wp-migrate-core convert <export.xml> --out <new-site> [--target astro]
+  wp-migrate-core report <export.xml> [--out migration-report.html]
+  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
+
+This is a deliberately incomplete demonstration. It does not modify WordPress.`;
+}
+function parseArguments(argv) {
+    const command = argv[0] ?? "help";
+    let input;
+    let output;
+    let target = "astro";
+    for (let index = 1; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === "--out") {
+            output = argv[index + 1];
+            index += 1;
+        }
+        else if (value === "--target") {
+            const candidate = argv[index + 1];
+            if (candidate !== "astro" && candidate !== "next" && candidate !== "nuxt") {
+                throw new Error(`Unknown target: ${candidate ?? "missing"}. Use astro, next, or nuxt.`);
+            }
+            target = candidate;
+            index += 1;
+        }
+        else if (!value?.startsWith("--") && input === undefined) {
+            input = value;
+        }
+        else {
+            throw new Error(`Unknown argument: ${value ?? "missing"}`);
+        }
+    }
+    return { command, ...(input === undefined ? {} : { input }), ...(output === undefined ? {} : { output }), target };
+}
+async function loadProject(inputPath) {
+    const xml = await readFile(resolve(inputPath), "utf8");
+    return parseWxr(xml);
+}
+/**
+ * Keep the default CLI plan useful for migration review without copying source
+ * content, post metadata, parser attributes, diagnostic snippets, or
+ * unsanitized source URLs into the default local review file.
+ */
+function createMigrationPlan(project) {
+    return {
+        site: { title: project.site.title },
+        source: project.source.title === undefined ? {} : { title: project.source.title },
+        records: project.records.map(createPlanRecord),
+        issues: project.issues.map(createPlanIssue),
+        summary: project.summary
+    };
+}
+function createPlanRecord(record) {
+    const route = sanitizePlanRoute(record.route);
+    return {
+        sourceId: record.sourceId,
+        wordpressId: record.wordpressId,
+        type: record.type,
+        status: record.status,
+        title: record.title,
+        slug: record.slug,
+        ...(route === undefined ? {} : { route }),
+        ...(record.publishedAt === undefined ? {} : { publishedAt: record.publishedAt }),
+        ...(record.modifiedAt === undefined ? {} : { modifiedAt: record.modifiedAt }),
+        editor: record.editor,
+        nodes: record.nodes.map(createPlanNode),
+        issues: record.issues.map(createPlanIssue)
+    };
+}
+function createPlanNode(node) {
+    return {
+        id: node.id,
+        source: node.source,
+        sourceType: node.sourceType,
+        kind: node.kind,
+        conversion: node.conversion,
+        children: node.children.map(createPlanNode)
+    };
+}
+function createPlanIssue(issue) {
+    const route = sanitizePlanRoute(issue.route);
+    return {
+        id: issue.id,
+        severity: issue.severity,
+        code: issue.code,
+        sourceId: issue.sourceId,
+        ...(route === undefined ? {} : { route }),
+        ...(issue.nodeId === undefined ? {} : { nodeId: issue.nodeId }),
+        title: issue.title,
+        message: issue.message,
+        requiredAction: issue.requiredAction
+    };
+}
+function sanitizePlanRoute(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        const pathname = value.trim().split(/[?#]/, 1)[0] ?? "";
+        return pathname.startsWith("/") ? pathname : undefined;
+    }
+}
+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.`);
+}
+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 assertOutputDoesNotExist(outputPath) {
+    try {
+        await lstat(outputPath);
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    throw outputExistsError(outputPath);
+}
+async function writeNewFile(outputPath, contents) {
+    try {
+        await writeFile(outputPath, contents, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "EEXIST"))
+            throw outputExistsError(outputPath);
+        throw error;
+    }
+}
+function printSummary(project) {
+    const { summary } = project;
+    console.log(`\n${project.source.title ?? "WordPress export"}`);
+    console.log(`  ${summary.records} records`);
+    console.log(`  ${summary.nodes} detected content constructs`);
+    console.log(`  ${summary.nativeNodes} constructs marked as directly supported`);
+    console.log(`  ${summary.manualNodes} constructs need manual handling`);
+    console.log(`  ${summary.blockedNodes} blocked constructs`);
+    console.log(`  ${summary.blockers} blockers; ${summary.warnings} items need review`);
+    if (project.issues.length > 0) {
+        console.log("\nRepair queue");
+        for (const issue of project.issues) {
+            const marker = issue.severity === "blocker" ? "BLOCKED" : issue.severity.toUpperCase();
+            console.log(`  [${marker}] ${issue.route ?? "site-wide"}: ${issue.message}`);
+        }
+    }
+}
+async function inspect(project, outputDirectory) {
+    const directory = resolve(outputDirectory);
+    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}`);
+}
+async function run() {
+    const options = parseArguments(process.argv.slice(2));
+    if (options.command === "help" || options.command === "--help" || options.command === "-h") {
+        console.log(usage());
+        return;
+    }
+    if (options.command === "demo") {
+        assertTargetEnabled(options.target);
+        const fixture = fileURLToPath(new URL("../../fixtures/demo-wordpress.xml", import.meta.url));
+        const project = await loadProject(fixture);
+        const output = resolve(options.output ?? "wp-migrate-core-demo");
+        await inspect(project, resolve(output, "migration-plan"));
+        await generateAstroProject(project, resolve(output, "astro-site"));
+        await writeReport(project, resolve(output, "astro-site", "migration", "report.html"));
+        console.log(`Astro demo: ${resolve(output, "astro-site")}`);
+        return;
+    }
+    if (!options.input) {
+        throw new Error(`${options.command} requires a WordPress WXR file.\n\n${usage()}`);
+    }
+    const project = await loadProject(options.input);
+    if (options.command === "inspect") {
+        assertTargetEnabled(options.target);
+        await inspect(project, options.output ?? "migration-plan");
+        return;
+    }
+    if (options.command === "report") {
+        const output = resolve(options.output ?? "migration-report.html");
+        await writeReport(project, output, { noClobber: true });
+        printSummary(project);
+        console.log(`\nReport: ${output}`);
+        return;
+    }
+    if (options.command === "convert") {
+        assertTargetEnabled(options.target);
+        if (!options.output)
+            throw new Error("convert requires --out <new-site>.");
+        const output = resolve(options.output);
+        await generateAstroProject(project, output);
+        await writeReport(project, resolve(output, "migration", "report.html"));
+        printSummary(project);
+        console.log(`\nGenerated ${targetAvailability[options.target].label} project: ${output}`);
+        return;
+    }
+    throw new Error(`Unknown command: ${options.command}.\n\n${usage()}`);
+}
+run().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`wp-migrate-core: ${message}`);
+    process.exitCode = 1;
+});

package/dist/src/core.d.ts

@@ -0,0 +1,9 @@
+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.
+ */
+export declare function parseWxr(xml: string, options?: InspectOptions): MigrationProject;
+export declare const inspectWxr: typeof parseWxr;