@open-press/core 0.7.1 → 1.0.0

package/README.md

@@ -5,10 +5,10 @@ Framework runtime, CLI engine, and Press Tree primitives for [open-press](https:
 Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
 
 ```bash
-npx @open-press/cli init my-doc --pack editorial-monograph
+npx @open-press/cli init my-doc
 ```
 
-The scaffolded workspace contains a snapshot of this package.
+The scaffolded workspace contains a snapshot of this package. Starter files are supplied by skills, not by `@open-press/core`.
 
 ## Direct use
 
@@ -31,7 +31,10 @@ import { mdxSource } from "@open-press/core/mdx";
 import { Sections, Toc } from "@open-press/core/manuscript";
 ```
 
-`document/index.tsx` default-exports a `<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+`press/index.tsx` or transitional `document/index.tsx` default-exports a `<Workspace>/<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+
+For the maintenance contract around Press Tree, page geometry presets, and the
+allocation pipeline, see [`docs/press-tree.md`](https://github.com/quan0715/open-press/blob/main/docs/press-tree.md).
 
 The CLI bin (`open-press`) supports dev / build / preview / validate / pdf / deploy / export commands. It requires a workspace with `openpress.config.mjs` and the surrounding framework files (which the scaffolder installs).
 

package/engine/cli.mjs

@@ -4,25 +4,25 @@ 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";
+import * as imageCmd from "./commands/image.mjs";
 import * as pdfCmd from "./commands/pdf.mjs";
 import * as previewCmd from "./commands/preview.mjs";
 import * as replaceCmd from "./commands/replace.mjs";
 import * as renderCmd from "./commands/render.mjs";
 import * as searchCmd from "./commands/search.mjs";
+import * as skillsSyncCmd from "./commands/skills-sync.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 "./runtime/config.mjs";
-import { listStylePackSkills } from "./init.mjs";
 import { discoverWorkspace } from "./runtime/validation.mjs";
 
 const COMMANDS = {
-  init: initCmd,
   validate: validateCmd,
   inspect: inspectCmd,
+  image: imageCmd,
   search: searchCmd,
   replace: replaceCmd,
   export: exportCmd,
@@ -34,6 +34,8 @@ const COMMANDS = {
   deploy: deployCmd,
   doctor: doctorCmd,
   upgrade: upgradeCmd,
+  migrate: upgradeCmd,
+  "skills:sync": skillsSyncCmd,
 };
 
 const args = process.argv.slice(2);
@@ -71,12 +73,9 @@ async function main(commandName, argv) {
 }
 
 async function printHelp() {
-  const packs = await listStylePackSkills();
-  const skillList = packs.length ? packs.join(" | ") : "(none installed)";
   console.log(`Usage: node engine/cli.mjs <command> [path] [options]
 
 Commands:
-  init <target> [--skill <name>] [--force]
   validate
   inspect [--json] [--no-build] [--dry-run]
   search [path] <query> [--json] [--scope content|all]
@@ -86,11 +85,12 @@ Commands:
   preview --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   dev --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   typecheck
+  image [--output <outputDir>] [--no-build] [--dry-run]
   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}
+  migrate [--dry-run] [--no-deps] [--no-skills] [--json] # alias for upgrade; reads migration notes
+  skills:sync [--source <owner/repo>] [--dry-run]        # refresh installed agent skills
 `);
 }

package/engine/commands/_shared.mjs

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
+import { captureUrlPagesToPng, printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
 import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
 import { exportDocument } from "../document-export.mjs";
 import { optimizePdfMediaForStaticRoot } from "../output/pdf-media.mjs";
@@ -23,6 +23,9 @@ export function parseOptions(argv) {
     else if (value === "--force") options.force = true;
     else if (value === "--confirm") options.confirm = true;
     else if (value === "--json") options.json = true;
+    else if (value === "--no-cache") options.noCache = true;
+    else if (value === "--no-deps") options.noDeps = true;
+    else if (value === "--no-skills") options.noSkills = true;
     else if (value === "--no-build") options.noBuild = true;
     else if (value === "--apply") options.apply = true;
     else if (value === "--include-code") options.includeCode = true;
@@ -38,20 +41,6 @@ export function parseOptions(argv) {
   return options;
 }
 
-export function parseInitOptions(argv) {
-  const options = { force: false };
-  const positional = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const value = argv[i];
-    if (value === "--skill") options.skill = argv[++i];
-    else if (value === "--force") options.force = true;
-    else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
-    else positional.push(value);
-  }
-  options.target = positional[0];
-  return options;
-}
-
 export function formatDisplayPath(absolutePath) {
   const relative = path.relative(process.cwd(), absolutePath);
   if (!relative || relative.startsWith("..")) return absolutePath;
@@ -118,6 +107,39 @@ export async function buildReactPdf({
   return { pdfPath: outPath };
 }
 
+export async function buildReactImages({
+  root,
+  config,
+  outDir,
+  host = "127.0.0.1",
+  port = "5186",
+  noBuild = false,
+  recurse,
+}) {
+  config ??= await loadConfig(root);
+  outDir ??= path.join(config.paths.outputDir, "images");
+  const renderCode = await buildReactStatic({ root, noBuild, recurse });
+  if (renderCode !== 0) throw new Error(`React render failed with exit code ${renderCode}`);
+  await fs.mkdir(outDir, { recursive: true });
+
+  const server = await startStaticServer(root, config, host, port);
+  try {
+    const result = await captureUrlPagesToPng({
+      root,
+      url: `http://${host}:${port}/?print=1`,
+      outDir,
+      waitForReady: waitForPrintReady,
+      debuggingPortBase: 9700,
+      debuggingPortRange: 600,
+      profilePrefix: "chrome-image",
+    });
+    console.log(`${result.files.length} OpenPress pages exported to PNG`);
+    return { outDir, files: result.files, pageCount: result.pageCount };
+  } finally {
+    await stopChildProcess(server);
+  }
+}
+
 export function startStaticServer(root, config, host, port) {
   return new Promise((resolve, reject) => {
     const child = spawn("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], {

package/engine/commands/dev.mjs

@@ -16,7 +16,7 @@ export async function run({ root, options }) {
     if (!options.noBuild) {
       console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} export .`);
     }
-    console.log(`Command: npx vite --config vite.config.ts --host ${host} --port ${port}`);
+    console.log(`Command: npx vite --force --config vite.config.ts --host ${host} --port ${port}`);
     return 0;
   }
   if (!options.noBuild) {
@@ -27,7 +27,7 @@ export async function run({ root, options }) {
   await printDoctorNoticeIfStale(root);
 
   console.log(`OpenPress dev: ${url}`);
-  return runCommand("npx", ["vite", "--config", "vite.config.ts", "--host", host, "--port", port], root);
+  return runCommand("npx", ["vite", "--force", "--config", "vite.config.ts", "--host", host, "--port", port], root);
 }
 
 async function printDoctorNoticeIfStale(root) {

package/engine/commands/image.mjs

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { CLI_ENTRY, STATIC_SERVER, buildReactImages, formatNodeScriptCommand } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const outputDir = options.output ? path.resolve(root, options.output) : path.join(config.paths.outputDir, "images");
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5186";
+
+  if (options.dryRun) {
+    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(`Chrome image export URL: http://${host}:${port}/?print=1`);
+    console.log(`Output: ${path.relative(root, path.join(outputDir, "page-001.png"))}`);
+    return 0;
+  }
+
+  const result = await buildReactImages({
+    root,
+    config,
+    outDir: outputDir,
+    host,
+    port,
+    noBuild: options.noBuild,
+    recurse,
+  });
+
+  console.log(`OpenPress images: ${path.relative(root, result.outDir)} (${result.files.length} pages)`);
+  return 0;
+}

package/engine/commands/skills-sync.mjs

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { runCommand } from "./_shared.mjs";
+
+const DEFAULT_SOURCE = "quan0715/open-press";
+
+// Refresh installed agent skills against the workspace's lock file.
+// Behavior:
+//   - If skills-lock.json exists, run `npx skills upgrade` (refreshes all
+//     currently-installed sources to their latest published versions).
+//   - If skills-lock.json is missing, install the OpenPress framework
+//     skill bundle (and any user-supplied --source) as a first-time setup.
+//   - If a --source flag is passed, also add that source on top of any
+//     existing installations.
+//
+// Always exits 0 unless the underlying `skills` tool fails.
+export async function run({ root, options }) {
+  const lockPath = path.join(root, "skills-lock.json");
+  const lockExists = existsSync(lockPath);
+  const extraSource = options?.source;
+
+  if (options?.dryRun) {
+    if (lockExists) {
+      console.log("Command: npx -y skills@latest upgrade");
+    } else {
+      console.log(`Command: npx -y skills@latest add ${DEFAULT_SOURCE}`);
+    }
+    if (extraSource) {
+      console.log(`Command: npx -y skills@latest add ${extraSource}`);
+    }
+    return 0;
+  }
+
+  if (lockExists) {
+    const sources = await readLockSources(lockPath);
+    if (sources.length === 0) {
+      console.log("skills-lock.json has no sources; installing framework default…");
+      const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+      if (code !== 0) return code;
+    } else {
+      console.log(`Refreshing ${sources.length} installed source(s)…`);
+      for (const src of sources) console.log(`  ${src}`);
+      const code = await runCommand("npx", ["-y", "skills@latest", "upgrade"], root);
+      if (code !== 0) return code;
+    }
+  } else {
+    console.log(`No skills-lock.json; installing framework default: ${DEFAULT_SOURCE}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+    if (code !== 0) return code;
+  }
+
+  if (extraSource) {
+    console.log(`Adding extra source: ${extraSource}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", extraSource], root);
+    if (code !== 0) return code;
+  }
+
+  console.log("✓ Skills synced");
+  return 0;
+}
+
+async function readLockSources(lockPath) {
+  try {
+    const lock = JSON.parse(await readFile(lockPath, "utf8"));
+    const sources = Array.isArray(lock?.sources) ? lock.sources : [];
+    return sources.map((s) => s?.source).filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}

package/engine/commands/typecheck.mjs

@@ -1,5 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
 import { runCommand } from "./_shared.mjs";
 
+// Run typecheck via the locally installed typescript. The previous
+// implementation used `npx tsc`; npm 11 + Node 24 (our CI / release
+// pin) changed npx's bin lookup so it no longer walks pnpm's nested
+// `.bin/` symlink farm and falls back to fetching the legacy
+// `tsc@2.0.4` shim, which crashes.
+//
+// Resolution order:
+//   1. `node <resolved tsc>` via require.resolve(typescript/package.json)
+//      — works with npm-hoisted layouts and most pnpm installs.
+//   2. Walk up node_modules/.bin/tsc — covers downstream npm/yarn.
+//   3. Fall back to `pnpm exec tsc` — pnpm knows its own symlink farm
+//      even when bare require.resolve doesn't, which is what CI hits.
 export async function run({ root }) {
-  return runCommand("npx", ["tsc", "--noEmit", "-p", "tsconfig.json"], root);
+  const absoluteRoot = path.resolve(root);
+
+  const tscBin = resolveTscBin(absoluteRoot);
+  if (tscBin) {
+    return runCommand("node", [tscBin, "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  if (hasCommand("pnpm")) {
+    return runCommand("pnpm", ["exec", "tsc", "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  console.error("[openpress] typescript is not installed in this workspace.");
+  console.error("Add it with: npm install --save-dev typescript");
+  return 1;
+}
+
+function resolveTscBin(absoluteRoot) {
+  try {
+    const require = createRequire(path.join(absoluteRoot, "package.json"));
+    const pkgPath = require.resolve("typescript/package.json");
+    return path.join(path.dirname(pkgPath), "bin", "tsc");
+  } catch {
+    // fall through to .bin probe
+  }
+
+  let dir = absoluteRoot;
+  while (true) {
+    const candidate = path.join(dir, "node_modules", ".bin", "tsc");
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function hasCommand(name) {
+  const PATH = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      if (fs.existsSync(path.join(dir, name + ext))) return true;
+    }
+  }
+  return false;
 }

package/engine/commands/upgrade.mjs

@@ -46,7 +46,7 @@ export async function run({ root, options }) {
     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("  2. apply edits to press/ 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");
@@ -98,11 +98,11 @@ export async function run({ root, options }) {
       }
     }
     process.stdout.write(
-      "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
+      "\nAgent: open each file, identify document-level changes, grep press/ 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");
+  process.stdout.write("\nVerify with:\n  npm run build\n\n");
   return 0;
 }
 

package/engine/document-export.mjs

@@ -10,6 +10,6 @@ export async function exportDocument(root = ROOT) {
   if (reactResult) return reactResult;
 
   throw new Error(
-    "React/MDX document entry not found. Expected document/index.tsx with a Press default export before exporting.",
+    "React/MDX document entry not found. Expected press/index.tsx with a Press default export before exporting.",
   );
 }

package/engine/output/chrome-pdf.mjs

@@ -91,6 +91,13 @@ const DEFAULT_PRINT_OPTIONS = {
   marginLeft: 0,
 };
 
+export const DEFAULT_PRINT_VIEWPORT = Object.freeze({
+  width: 1200,
+  height: 1698,
+  deviceScaleFactor: 1,
+  mobile: false,
+});
+
 export async function printUrlToPdf({
   root,
   url,
@@ -98,6 +105,7 @@ export async function printUrlToPdf({
   chrome,
   waitForReady = waitForPrintReady,
   printOptions = {},
+  viewport = DEFAULT_PRINT_VIEWPORT,
   debuggingPortBase = 9600,
   debuggingPortRange = 300,
   profilePrefix = "chrome-pdf",
@@ -126,9 +134,7 @@ export async function printUrlToPdf({
     const tab = await waitForChromeTab(debuggingPort);
     const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
     try {
-      await client.send("Page.enable");
-      await client.send("Runtime.enable");
-      await client.send("Emulation.setEmulatedMedia", { media: "print" });
+      await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
       const readyResult = await waitForReady(client);
       const result = await client.send("Page.printToPDF", {
@@ -146,6 +152,87 @@ export async function printUrlToPdf({
   }
 }
 
+export async function captureUrlPagesToPng({
+  root,
+  url,
+  outDir,
+  chrome,
+  waitForReady = waitForPrintReady,
+  viewport = DEFAULT_PRINT_VIEWPORT,
+  debuggingPortBase = 9700,
+  debuggingPortRange = 300,
+  profilePrefix = "chrome-image",
+}) {
+  chrome ??= resolveChromePath();
+  await fs.mkdir(outDir, { recursive: true });
+
+  const debuggingPort = String(debuggingPortBase + Math.floor(Math.random() * debuggingPortRange));
+  const profileDir = path.join(root, ".openpress", "tmp", `${profilePrefix}-${process.pid}-${Date.now()}`);
+  await fs.mkdir(profileDir, { recursive: true });
+
+  const child = spawn(
+    chrome,
+    [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--remote-debugging-port=${debuggingPort}`,
+      `--user-data-dir=${profileDir}`,
+      "about:blank",
+    ],
+    { cwd: root, stdio: ["ignore", "pipe", "pipe"] },
+  );
+
+  try {
+    const tab = await waitForChromeTab(debuggingPort);
+    const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
+    try {
+      await preparePdfPage(client, { viewport });
+      await client.send("Page.navigate", { url });
+      const pageCount = await waitForReady(client);
+      const rects = await getPrintPageRects(client);
+      if (rects.length === 0) throw new Error("No OpenPress pages found for image export.");
+
+      const padWidth = Math.max(3, String(rects.length).length);
+      const files = [];
+      for (const [index, rect] of rects.entries()) {
+        const filename = `page-${String(index + 1).padStart(padWidth, "0")}.png`;
+        const filePath = path.join(outDir, filename);
+        const result = await client.send("Page.captureScreenshot", {
+          format: "png",
+          fromSurface: true,
+          captureBeyondViewport: true,
+          clip: {
+            x: Math.max(0, rect.x),
+            y: Math.max(0, rect.y),
+            width: rect.width,
+            height: rect.height,
+            scale: 1,
+          },
+        });
+        await fs.writeFile(filePath, Buffer.from(String(result.data ?? ""), "base64"));
+        files.push(filePath);
+      }
+
+      return { pageCount, files };
+    } finally {
+      client.close();
+    }
+  } finally {
+    await stopChildProcess(child);
+    await cleanupChromeProfile(profileDir);
+  }
+}
+
+export async function preparePdfPage(client, { viewport = DEFAULT_PRINT_VIEWPORT } = {}) {
+  await client.send("Page.enable");
+  await client.send("Runtime.enable");
+  if (viewport) {
+    await client.send("Emulation.setDeviceMetricsOverride", viewport);
+  }
+  await client.send("Emulation.setEmulatedMedia", { media: "print" });
+}
+
 export async function evaluateUrlWithChrome({
   root,
   url,
@@ -250,6 +337,26 @@ export async function waitForPrintReady(client) {
   throw new Error("Timed out waiting for OpenPress pagination before PDF export.");
 }
 
+async function getPrintPageRects(client) {
+  const result = await client.send("Runtime.evaluate", {
+    returnByValue: true,
+    expression: `(() => {
+      return Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page')).map((page, index) => {
+        const target = page.querySelector('.openpress-html-page__html') || page;
+        const rect = target.getBoundingClientRect();
+        return {
+          index,
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        };
+      }).filter((rect) => rect.width > 0 && rect.height > 0);
+    })()`,
+  });
+  return Array.isArray(result.result?.value) ? result.result.value : [];
+}
+
 export async function stopChildProcess(child) {
   if (child.exitCode !== null || child.signalCode !== null) return;
   child.kill();