@open-press/core 0.3.0 → 0.6.0

package/engine/cli.mjs

@@ -2,6 +2,7 @@
 
 import * as deployCmd from "./commands/deploy.mjs";
 import * as devCmd from "./commands/dev.mjs";
+import * as doctorCmd from "./commands/doctor.mjs";
 import * as exportCmd from "./commands/export.mjs";
 import * as initCmd from "./commands/init.mjs";
 import * as inspectCmd from "./commands/inspect.mjs";
@@ -12,6 +13,7 @@ import * as replaceCmd from "./commands/replace.mjs";
 import * as renderCmd from "./commands/render.mjs";
 import * as searchCmd from "./commands/search.mjs";
 import * as typecheckCmd from "./commands/typecheck.mjs";
+import * as upgradeCmd from "./commands/upgrade.mjs";
 import * as validateCmd from "./commands/validate.mjs";
 import { parseOptions } from "./commands/_shared.mjs";
 import { loadConfig } from "./config.mjs";
@@ -32,6 +34,8 @@ const COMMANDS = {
   typecheck: typecheckCmd,
   pdf: pdfCmd,
   deploy: deployCmd,
+  doctor: doctorCmd,
+  upgrade: upgradeCmd,
 };
 
 const args = process.argv.slice(2);
@@ -87,6 +91,8 @@ Commands:
   typecheck
   pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
+  doctor [--json] [--no-cache]                          # version + skill staleness check
+  upgrade [--dry-run] [--no-deps] [--no-skills] [--json] # apply updates; agent-driven
 
 Style packs available for \`init --skill\`: ${skillList}
 `);

package/engine/commands/_shared.mjs

@@ -7,8 +7,9 @@ import { loadConfig, publicPdfHref } from "../config.mjs";
 import { exportDocument } from "../document-export.mjs";
 import { optimizePdfMediaForStaticRoot } from "../pdf-media.mjs";
 
-const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const STATIC_SERVER = path.join(ENGINE_DIR, "static-server.mjs");
+export const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const CLI_ENTRY = path.join(ENGINE_DIR, "cli.mjs");
+export const STATIC_SERVER = path.join(ENGINE_DIR, "static-server.mjs");
 
 export function parseOptions(argv) {
   const options = {};
@@ -62,6 +63,12 @@ export function runCommand(commandName, commandArgs, cwd) {
   return result.status ?? 1;
 }
 
+export function formatNodeScriptCommand(root, scriptPath) {
+  const relative = path.relative(root, scriptPath).replaceAll("\\", "/");
+  const displayPath = relative && !relative.startsWith("../") ? relative : scriptPath;
+  return `node ${displayPath}`;
+}
+
 export async function buildReactStatic({ root, noBuild = false, recurse, silent = false }) {
   if (noBuild) return 0;
   if (!silent) {

package/engine/commands/deploy.mjs

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { deploySync } from "../deploy-sync.mjs";
-import { buildReactPdf, runCommand, writePdfStageDeployConfig } from "./_shared.mjs";
+import { CLI_ENTRY, buildReactPdf, formatNodeScriptCommand, runCommand, writePdfStageDeployConfig } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   if (config.deploy.requiresConfirmation === true && !options.confirm) {
@@ -12,9 +12,9 @@ export async function run({ root, config, options, recurse }) {
   const commitDirty = config.deploy.commitDirty;
   if (options.dryRun) {
     console.log("OpenPress deploy dry run");
-    console.log("Command: node engine/cli.mjs render . --renderer react");
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
     console.log(`Step:    deploy-sync (copy ${config.outputDir} → ${source})`);
-    console.log(`Command: node engine/cli.mjs pdf . --output ${source}/${config.pdf.filename}`);
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} pdf . --output ${source}/${config.pdf.filename}`);
     console.log(`Step:    write ${source}/openpress/deploy.json with deployment metadata`);
     console.log(`Command: npx wrangler pages deploy ${source}${projectName ? ` --project-name=${projectName}` : ""}${commitDirty ? " --commit-dirty=true" : ""}`);
     return 0;

package/engine/commands/dev.mjs

@@ -1,5 +1,6 @@
 import { exportDocument } from "../document-export.mjs";
-import { runCommand } from "./_shared.mjs";
+import { diagnose } from "./doctor.mjs";
+import { CLI_ENTRY, formatNodeScriptCommand, runCommand } from "./_shared.mjs";
 
 export async function run({ root, options }) {
   const renderer = options.renderer ?? "react";
@@ -13,7 +14,7 @@ export async function run({ root, options }) {
   if (options.dryRun) {
     console.log(`OpenPress dev URL: ${url}`);
     if (!options.noBuild) {
-      console.log("Command: node engine/cli.mjs export .");
+      console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} export .`);
     }
     console.log(`Command: npx vite --config vite.config.ts --host ${host} --port ${port}`);
     return 0;
@@ -21,6 +22,28 @@ export async function run({ root, options }) {
   if (!options.noBuild) {
     await exportDocument(root);
   }
+
+  // One-line update notice (24h cached, network failure is silent).
+  await printDoctorNoticeIfStale(root);
+
   console.log(`OpenPress dev: ${url}`);
   return runCommand("npx", ["vite", "--config", "vite.config.ts", "--host", host, "--port", port], root);
 }
+
+async function printDoctorNoticeIfStale(root) {
+  try {
+    const report = await diagnose(root);
+    if (!report.stale) return;
+    const parts = [];
+    if (report.coreUpdateAvailable) {
+      parts.push(`@open-press/core ${report.coreVersion} → ${report.coreLatest}`);
+    }
+    if (report.pendingMigrations.length > 0) {
+      parts.push(`${report.pendingMigrations.length} migration note(s)`);
+    }
+    if (parts.length === 0) return;
+    console.log(`○ open-press: ${parts.join(" · ")} — run \`npx open-press doctor\` for details.`);
+  } catch {
+    // Doctor is informational only; never block dev.
+  }
+}

package/engine/commands/doctor.mjs

@@ -0,0 +1,229 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const CORE_PACKAGE = "@open-press/core";
+
+export async function run({ root, options }) {
+  const json = Boolean(options?.json);
+  const noCache = Boolean(options?.noCache);
+
+  const report = await diagnose(root, { noCache });
+
+  if (json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    printHumanReport(report);
+  }
+
+  // Exit 0 even when stale — doctor is informational, not a gate.
+  // Agents / CI can check report.stale or report.coreUpdateAvailable.
+  return 0;
+}
+
+/**
+ * Diagnose workspace against latest framework state.
+ * Result shape:
+ *   {
+ *     coreVersion: "0.4.0",                    // installed
+ *     coreLatest: "0.5.0" | null,              // null on network failure
+ *     coreUpdateAvailable: boolean,
+ *     skillsInstalled: ["openpress", ...],
+ *     skillsLockSource: "quan0715/open-press" | null,
+ *     pendingMigrations: ["0.5.0"],            // versions with docs/migrations notes
+ *     stale: boolean,                          // either core or skills behind
+ *     cachedAt: ISO timestamp
+ *   }
+ */
+export async function diagnose(root, { noCache = false } = {}) {
+  const cachePath = path.join(root, ".openpress", "cache", "doctor.json");
+
+  if (!noCache) {
+    const cached = await readCached(cachePath);
+    if (cached) return cached;
+  }
+
+  const coreVersion = await readCoreVersion(root);
+  const coreLatest = await fetchCoreLatest();
+  const skillsInstalled = await listInstalledSkills(root);
+  const skillsLockSource = await readSkillsLockSource(root);
+  const pendingMigrations = await listPendingMigrations(root, coreVersion, coreLatest);
+
+  const coreUpdateAvailable = Boolean(
+    coreVersion && coreLatest && coreVersion !== coreLatest && semverLt(coreVersion, coreLatest),
+  );
+
+  const report = {
+    coreVersion,
+    coreLatest,
+    coreUpdateAvailable,
+    skillsInstalled,
+    skillsLockSource,
+    pendingMigrations,
+    stale: coreUpdateAvailable || pendingMigrations.length > 0,
+    cachedAt: new Date().toISOString(),
+  };
+
+  await writeCached(cachePath, report).catch(() => {});
+  return report;
+}
+
+async function readCached(cachePath) {
+  try {
+    const stats = await stat(cachePath);
+    if (Date.now() - stats.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(await readFile(cachePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCached(cachePath, report) {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  await writeFile(cachePath, JSON.stringify(report, null, 2) + "\n", "utf8");
+}
+
+async function readCoreVersion(root) {
+  // Try workspace package.json deps first; fall back to installed package.
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const range = pkg.dependencies?.[CORE_PACKAGE] ?? pkg.devDependencies?.[CORE_PACKAGE];
+    if (range) {
+      // Try the installed version (more accurate than the range).
+      try {
+        const installed = JSON.parse(
+          await readFile(path.join(root, "node_modules", CORE_PACKAGE, "package.json"), "utf8"),
+        );
+        return installed.version;
+      } catch {
+        return range.replace(/^[\^~>=<\s]+/, "");
+      }
+    }
+  } catch {}
+
+  // Self-bundled framework (cli scaffolded workspace): pkg.version is the framework version.
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    if (pkg.name === CORE_PACKAGE) return pkg.version;
+  } catch {}
+
+  return null;
+}
+
+async function fetchCoreLatest() {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${CORE_PACKAGE}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+
+async function listInstalledSkills(root) {
+  const skillsDir = path.join(root, ".agents", "skills");
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+async function readSkillsLockSource(root) {
+  try {
+    const lock = JSON.parse(await readFile(path.join(root, "skills-lock.json"), "utf8"));
+    const sources = lock?.sources;
+    if (Array.isArray(sources) && sources.length > 0) return sources[0]?.source ?? null;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function listPendingMigrations(root, currentVersion, latestVersion) {
+  if (!currentVersion || !latestVersion || !semverLt(currentVersion, latestVersion)) return [];
+  // Look for docs/migrations/<version>.md files for versions in (current, latest].
+  const migrationsDir = path.join(root, "docs", "migrations");
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(migrationsDir);
+    return files
+      .filter((f) => /^\d+\.\d+\.\d+\.md$/.test(f))
+      .map((f) => f.replace(/\.md$/, ""))
+      .filter((v) => semverGt(v, currentVersion) && !semverGt(v, latestVersion))
+      .sort(semverCompare);
+  } catch {
+    return [];
+  }
+}
+
+function semverParse(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return [0, 0, 0];
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function semverCompare(a, b) {
+  const A = semverParse(a);
+  const B = semverParse(b);
+  for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] - B[i];
+  return 0;
+}
+function semverLt(a, b) { return semverCompare(a, b) < 0; }
+function semverGt(a, b) { return semverCompare(a, b) > 0; }
+
+function printHumanReport(report) {
+  const lines = [];
+  lines.push("○ open-press doctor");
+  lines.push("");
+  lines.push("framework");
+  if (report.coreVersion) {
+    if (report.coreLatest === null) {
+      lines.push(`  ? @open-press/core: ${report.coreVersion} installed (couldn't check latest — offline?)`);
+    } else if (report.coreUpdateAvailable) {
+      lines.push(`  ⚠ @open-press/core: ${report.coreVersion} installed → ${report.coreLatest} available`);
+    } else {
+      lines.push(`  ✓ @open-press/core: ${report.coreVersion} (latest)`);
+    }
+  } else {
+    lines.push("  ? @open-press/core: not detected in this workspace");
+  }
+  lines.push("");
+  lines.push("skills");
+  if (report.skillsInstalled.length === 0) {
+    lines.push("  ? no skills installed under .agents/skills/");
+    lines.push("    run: npx skills add quan0715/open-press");
+  } else {
+    lines.push(`  ✓ ${report.skillsInstalled.length} skills installed`);
+    if (report.skillsLockSource) {
+      lines.push(`    source: ${report.skillsLockSource}`);
+      lines.push("    refresh: npx skills upgrade");
+    }
+  }
+  lines.push("");
+  lines.push("migrations");
+  if (report.pendingMigrations.length === 0) {
+    if (report.coreUpdateAvailable) {
+      lines.push(`  ✓ no breaking migrations documented for the ${report.coreLatest} window`);
+    } else {
+      lines.push("  ✓ up to date");
+    }
+  } else {
+    lines.push(`  ⚠ ${report.pendingMigrations.length} migration note(s) since your version:`);
+    for (const v of report.pendingMigrations) lines.push(`    - docs/migrations/${v}.md`);
+  }
+  lines.push("");
+  if (report.stale) {
+    lines.push("next");
+    lines.push("  npx open-press upgrade        # apply all updates (agent-driven)");
+    lines.push("  npx open-press doctor --json  # machine-readable output");
+    lines.push("");
+  }
+  process.stdout.write(lines.join("\n"));
+}

package/engine/commands/pdf.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { buildReactPdf } from "./_shared.mjs";
+import { CLI_ENTRY, STATIC_SERVER, buildReactPdf, formatNodeScriptCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const outputPath = options.output ? path.resolve(root, options.output) : undefined;
@@ -7,8 +7,8 @@ export async function run({ root, config, options, recurse }) {
     const relOutput = path.relative(root, outputPath ?? config.paths.pdf);
     const host = options.host ?? "127.0.0.1";
     const port = options.port ?? "5185";
-    console.log("Command: node engine/cli.mjs render . --renderer react");
-    console.log(`Command: node engine/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     console.log(`Command: Chrome --print-to-pdf=${relOutput} http://${host}:${port}/?print=1`);
     return 0;
   }

package/engine/commands/preview.mjs

@@ -1,4 +1,4 @@
-import { runCommand } from "./_shared.mjs";
+import { CLI_ENTRY, STATIC_SERVER, formatNodeScriptCommand, runCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const renderer = options.renderer ?? "react";
@@ -12,9 +12,9 @@ export async function run({ root, config, options, recurse }) {
   if (options.dryRun) {
     console.log(`OpenPress preview URL: ${url}`);
     if (!options.noBuild) {
-      console.log("Command: node engine/cli.mjs render . --renderer react");
+      console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
     }
-    console.log(`Command: node engine/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     return 0;
   }
   if (!options.noBuild) {
@@ -22,5 +22,5 @@ export async function run({ root, config, options, recurse }) {
     if (renderCode !== 0) return renderCode;
   }
   console.log(`OpenPress preview: ${url}`);
-  return runCommand("node", ["engine/static-server.mjs", config.outputDir, "--host", host, "--port", port, "--workspace", "."], root);
+  return runCommand("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], root);
 }

package/engine/commands/upgrade.mjs

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { diagnose } from "./doctor.mjs";
+import { runCommand } from "./_shared.mjs";
+
+export async function run({ root, options }) {
+  const dryRun = Boolean(options?.dryRun);
+  const skipSkills = Boolean(options?.noSkills);
+  const skipDeps = Boolean(options?.noDeps);
+  const json = Boolean(options?.json);
+
+  // 1. Fresh diagnose (force re-check, ignore cache).
+  const before = await diagnose(root, { noCache: true });
+
+  if (!before.stale) {
+    const message = "open-press is already up to date.";
+    if (json) {
+      process.stdout.write(JSON.stringify({ status: "noop", before }, null, 2) + "\n");
+    } else {
+      process.stdout.write(`✓ ${message}\n`);
+    }
+    return 0;
+  }
+
+  if (!json) {
+    process.stdout.write("○ open-press upgrade\n\n");
+    if (before.coreUpdateAvailable) {
+      process.stdout.write(
+        `  @open-press/core: ${before.coreVersion} → ${before.coreLatest}\n`,
+      );
+    }
+    if (before.pendingMigrations.length > 0) {
+      process.stdout.write(`  migration notes: ${before.pendingMigrations.join(", ")}\n`);
+    }
+    process.stdout.write("\n");
+  }
+
+  if (dryRun) {
+    if (!json) {
+      process.stdout.write("dry run — nothing changed. The agent should:\n");
+      process.stdout.write("  1. read each docs/migrations/<version>.md for document-level changes\n");
+      process.stdout.write("  2. apply edits to document/ where needed\n");
+      process.stdout.write("  3. re-run: npx open-press upgrade   (without --dry-run)\n");
+    } else {
+      process.stdout.write(JSON.stringify({ status: "dry-run", before }, null, 2) + "\n");
+    }
+    return 0;
+  }
+
+  // 2. Refresh framework dep (only when workspace declares @open-press/core).
+  if (!skipDeps && (await hasCoreDep(root))) {
+    if (!json) process.stdout.write("▸ updating @open-press/core via npm…\n");
+    const code = runCommand("npm", ["update", "@open-press/core"], root);
+    if (code !== 0) {
+      if (!json) process.stdout.write("  ⚠ npm update returned non-zero; continuing\n");
+    }
+  }
+
+  // 3. Refresh skills (npx skills upgrade respects skills-lock.json).
+  if (!skipSkills) {
+    if (!json) process.stdout.write("▸ refreshing skills via npx skills upgrade…\n");
+    runCommand("npx", ["-y", "skills@latest", "upgrade"], root);
+  }
+
+  // 4. Surface migration notes for the agent to read.
+  const migrationContents = await loadMigrations(root, before.pendingMigrations);
+
+  // 5. Re-diagnose to confirm the move.
+  const after = await diagnose(root, { noCache: true });
+
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        { status: "applied", before, after, migrationContents: migrationContents.map((m) => m.path) },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 0;
+  }
+
+  process.stdout.write("\n✓ upgrade applied. Now read these migration notes:\n\n");
+  if (migrationContents.length === 0) {
+    process.stdout.write("  (no migration docs in this version range)\n\n");
+  } else {
+    for (const m of migrationContents) {
+      process.stdout.write(`  ─ ${m.path}\n`);
+    }
+    process.stdout.write(
+      "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
+    );
+  }
+
+  process.stdout.write("\nVerify with:\n  npm run openpress:validate\n  npm run openpress:render\n\n");
+  return 0;
+}
+
+async function hasCoreDep(root) {
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    return Boolean(pkg.dependencies?.["@open-press/core"] || pkg.devDependencies?.["@open-press/core"]);
+  } catch {
+    return false;
+  }
+}
+
+async function loadMigrations(root, versions) {
+  const results = [];
+  for (const v of versions) {
+    const p = path.join(root, "docs", "migrations", `${v}.md`);
+    if (existsSync(p)) {
+      results.push({ version: v, path: path.relative(root, p) });
+    }
+  }
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",
@@ -48,6 +48,8 @@
     "js-yaml": "^4.1.1",
     "katex": "^0.16.47",
     "lucide-react": "^1.16.0",
+    "playwright": "^1.60.0",
+    "postcss": "^8.5.6",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "rehype-katex": "^7.0.1",

package/vite.config.ts

@@ -9,13 +9,18 @@ import { loadConfig, publicPdfHref } from "./engine/config.mjs";
 import { handleCommentRequest } from "./engine/react/comment-endpoint.mjs";
 import { handleProjectAssetRequest } from "./engine/react/project-asset-endpoint.mjs";
 
-const sourceRoot = fileURLToPath(new URL("./src", import.meta.url));
-const workspaceRoot = fileURLToPath(new URL("./", import.meta.url));
-const openpressCoreEntry = fileURLToPath(new URL("./src/openpress/core/index.tsx", import.meta.url));
-const reactDocumentComponentsRoot = path.join(workspaceRoot, "document", "components");
+const frameworkRoot = fileURLToPath(new URL("./", import.meta.url));
+const workspaceRoot = process.env.OPENPRESS_WORKSPACE_ROOT
+  ? path.resolve(process.env.OPENPRESS_WORKSPACE_ROOT)
+  : frameworkRoot;
+const sourceRoot = path.join(frameworkRoot, "src");
+const openpressCliPath = path.join(frameworkRoot, "engine", "cli.mjs");
+const staticServerPath = path.join(frameworkRoot, "engine", "static-server.mjs");
+const openpressCoreEntry = path.join(frameworkRoot, "src", "openpress", "core", "index.tsx");
 const openpressConfig = await loadConfig(workspaceRoot);
 const outputDir = openpressConfig.paths.outputDir;
-const reactDocumentRoot = path.join(workspaceRoot, "document");
+const reactDocumentRoot = openpressConfig.paths.documentRoot;
+const reactDocumentComponentsRoot = openpressConfig.paths.componentsDir;
 const reactDocumentEntry = path.join(reactDocumentRoot, "index.tsx");
 const activeContentDir = await fileExists(reactDocumentEntry)
   ? path.join(reactDocumentRoot, "chapters")
@@ -48,6 +53,7 @@ export default defineConfig({
   plugins: [openpressLocalDeployPlugin(), react()],
   define: workspaceDefines,
   resolve: {
+    dedupe: ["react", "react-dom", "@mdx-js/react"],
     alias: {
       "@openpress/core": openpressCoreEntry,
       "@/components": reactDocumentComponentsRoot,
@@ -69,6 +75,9 @@ export default defineConfig({
   server: {
     host: "127.0.0.1",
     port: 5173,
+    fs: {
+      allow: Array.from(new Set([frameworkRoot, workspaceRoot])),
+    },
     watch: {
       ignored: ["**/.openpress/tmp/**", `**/${openpressConfig.outputDir}/**`],
     },
@@ -201,7 +210,7 @@ async function handleLocalPdfExportRequest(req: IncomingMessage, res: ServerResp
     ok: result.code === 0 && exists,
     code: result.code,
     pdf: `/__openpress/local-pdf-file?ts=${Date.now()}`,
-    command: "node engine/cli.mjs pdf .",
+    command: openpressCliCommand(["pdf", "."]),
     stdout: result.stdout,
     stderr: result.stderr,
   });
@@ -266,7 +275,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
       deploy_adapter: openpressConfig.deploy.adapter,
       deploy_source: openpressConfig.deploy.source,
       deploy_project_name: openpressConfig.deploy.projectName,
-      command: "node engine/cli.mjs deploy . --confirm",
+      command: openpressCliCommand(["deploy", ".", "--confirm"]),
     });
     return;
   }
@@ -285,7 +294,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
     pdf: deployedUrl ? `${deployedUrl}/${openpressConfig.pdf.filename}` : deploymentInfo.pdf,
     public_url: publicUrl,
     dirty: false,
-    command: "node engine/cli.mjs deploy . --confirm",
+    command: openpressCliCommand(["deploy", ".", "--confirm"]),
     stdout: result.stdout,
     stderr: result.stderr,
   });
@@ -293,7 +302,7 @@ async function handleLocalDeployRequest(req: IncomingMessage, res: ServerRespons
 
 function runLocalPdfExport() {
   return new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn("node", ["engine/cli.mjs", "pdf", "."], {
+    const child = spawn("node", [openpressCliPath, "pdf", "."], {
       cwd: workspaceRoot,
       shell: false,
     });
@@ -316,7 +325,7 @@ function runLocalPdfExport() {
 
 function runLocalDeploy() {
   return new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
-    const child = spawn("node", ["engine/cli.mjs", "deploy", ".", "--confirm"], {
+    const child = spawn("node", [openpressCliPath, "deploy", ".", "--confirm"], {
       cwd: workspaceRoot,
       shell: false,
     });
@@ -405,7 +414,7 @@ function getLocalDeploymentSourcePaths() {
     openpressConfig.paths.themeDir,
     openpressConfig.paths.designDoc,
     openpressConfig.paths.componentsDir,
-    path.join(workspaceRoot, "src"),
+    path.join(frameworkRoot, "src"),
     path.join(workspaceRoot, "index.html"),
     path.join(workspaceRoot, "package.json"),
     path.join(workspaceRoot, "openpress.config.mjs"),
@@ -414,6 +423,12 @@ function getLocalDeploymentSourcePaths() {
   ];
 }
 
+function openpressCliCommand(args: string[]) {
+  const relativeCliPath = path.relative(workspaceRoot, openpressCliPath).replaceAll("\\", "/");
+  const displayCliPath = relativeCliPath && !relativeCliPath.startsWith("../") ? relativeCliPath : openpressCliPath;
+  return `node ${displayCliPath} ${args.join(" ")}`;
+}
+
 async function findNewestLocalSourceMtime(paths: string[]) {
   const times = await Promise.all(paths.map((sourcePath) => findNewestLocalMtime(sourcePath)));
   return Math.max(0, ...times);