@open-press/core 0.8.0 → 1.1.0

package/README.md

@@ -1,14 +1,14 @@
 # @open-press/core
 
-Framework runtime, CLI engine, and Press Tree primitives for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
+Package-owned runtime, render engine, and Press Tree primitives for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
 
 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 depends on this package; it does not vendor a copy of the runtime. Starter files are supplied by skills or by project-specific `press/` source files.
 
 ## Direct use
 
@@ -31,9 +31,21 @@ 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.
 
-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).
+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 public CLI bin lives in `@open-press/cli` and delegates runtime commands to this package:
+
+```bash
+npm install @open-press/core @open-press/cli
+npx open-press dev .
+npx open-press render .
+npx open-press pdf .
+```
+
+`@open-press/core` owns the internal browser shell (`index.html`), Vite config, React app runtime, render pipeline, and static server. A workspace owns `press/`, `package.json`, media, components, and theme files.
 
 ## License
 

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]
+  console.log(`Usage: open-press <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

@@ -1,15 +1,22 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 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";
 
 export const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const FRAMEWORK_ROOT = path.resolve(ENGINE_DIR, "..");
 export const CLI_ENTRY = path.join(ENGINE_DIR, "cli.mjs");
 export const STATIC_SERVER = path.join(ENGINE_DIR, "output", "static-server.mjs");
+export const VITE_CONFIG = path.join(FRAMEWORK_ROOT, "vite.config.ts");
+
+const require = createRequire(import.meta.url);
+const VITE_PACKAGE_JSON = require.resolve("vite/package.json");
+export const VITE_BIN = path.join(path.dirname(VITE_PACKAGE_JSON), "bin", "vite.js");
 
 export function parseOptions(argv) {
   const options = {};
@@ -23,6 +30,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,28 +48,18 @@ 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;
   return relative;
 }
 
-export function runCommand(commandName, commandArgs, cwd) {
-  const result = spawnSync(commandName, commandArgs, { cwd, stdio: "inherit" });
+export function runCommand(commandName, commandArgs, cwd, opts = {}) {
+  const result = spawnSync(commandName, commandArgs, {
+    cwd,
+    env: { ...process.env, ...(opts.env ?? {}) },
+    stdio: "inherit",
+  });
   return result.status ?? 1;
 }
 
@@ -69,6 +69,24 @@ export function formatNodeScriptCommand(root, scriptPath) {
   return `node ${displayPath}`;
 }
 
+export function formatOpenPressCommand(args = []) {
+  return `open-press ${args.join(" ")}`.trim();
+}
+
+export function workspaceRuntimeEnv(root) {
+  return { OPENPRESS_WORKSPACE_ROOT: path.resolve(root) };
+}
+
+export function viteCommandArgs(args = []) {
+  return [VITE_BIN, ...args];
+}
+
+export function formatViteCommand(root, args = []) {
+  const script = formatNodeScriptCommand(root, VITE_BIN);
+  const config = formatDisplayPath(VITE_CONFIG);
+  return `${script} ${args.join(" ")} --config ${config}`.replace(/\s+/g, " ").trim();
+}
+
 export async function buildReactStatic({ root, noBuild = false, recurse, silent = false }) {
   if (noBuild) return 0;
   if (!silent) {
@@ -76,9 +94,10 @@ export async function buildReactStatic({ root, noBuild = false, recurse, silent
   }
 
   await exportDocument(root);
-  const result = spawnSync("npx", ["vite", "build", "--config", "vite.config.ts"], {
+  const result = spawnSync("node", viteCommandArgs(["build", "--config", VITE_CONFIG]), {
     cwd: root,
     encoding: "utf8",
+    env: { ...process.env, ...workspaceRuntimeEnv(root) },
   });
   return result.status ?? 1;
 }
@@ -118,6 +137,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/deploy.mjs

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { deploySync } from "../output/deploy-sync.mjs";
-import { CLI_ENTRY, buildReactPdf, formatNodeScriptCommand, runCommand, writePdfStageDeployConfig } from "./_shared.mjs";
+import { buildReactPdf, formatOpenPressCommand, 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: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     console.log(`Step:    deploy-sync (copy ${config.outputDir} → ${source})`);
-    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} pdf . --output ${source}/${config.pdf.filename}`);
+    console.log(`Command: ${formatOpenPressCommand(["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,6 +1,13 @@
 import { exportDocument } from "../document-export.mjs";
 import { diagnose } from "./doctor.mjs";
-import { CLI_ENTRY, formatNodeScriptCommand, runCommand } from "./_shared.mjs";
+import {
+  VITE_CONFIG,
+  formatOpenPressCommand,
+  formatViteCommand,
+  runCommand,
+  viteCommandArgs,
+  workspaceRuntimeEnv,
+} from "./_shared.mjs";
 
 export async function run({ root, options }) {
   const renderer = options.renderer ?? "react";
@@ -14,9 +21,9 @@ export async function run({ root, options }) {
   if (options.dryRun) {
     console.log(`OpenPress dev URL: ${url}`);
     if (!options.noBuild) {
-      console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} export .`);
+      console.log(`Command: ${formatOpenPressCommand(["export", "."])}`);
     }
-    console.log(`Command: npx vite --force --config vite.config.ts --host ${host} --port ${port}`);
+    console.log(`Command: ${formatViteCommand(root, ["--force", "--host", host, "--port", port])}`);
     return 0;
   }
   if (!options.noBuild) {
@@ -27,7 +34,9 @@ export async function run({ root, options }) {
   await printDoctorNoticeIfStale(root);
 
   console.log(`OpenPress dev: ${url}`);
-  return runCommand("npx", ["vite", "--force", "--config", "vite.config.ts", "--host", host, "--port", port], root);
+  return runCommand("node", viteCommandArgs(["--force", "--config", VITE_CONFIG, "--host", host, "--port", port]), root, {
+    env: workspaceRuntimeEnv(root),
+  });
 }
 
 async function printDoctorNoticeIfStale(root) {

package/engine/commands/image.mjs

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { STATIC_SERVER, buildReactImages, formatNodeScriptCommand, formatOpenPressCommand } 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: ${formatOpenPressCommand(["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/inspect.mjs

@@ -1,5 +1,6 @@
 import { inspectWorkspace } from "../runtime/inspection.mjs";
 import { exitCodeForIssueReport } from "../runtime/issue-report.mjs";
+import { STATIC_SERVER, formatNodeScriptCommand, formatOpenPressCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const host = options.host ?? "127.0.0.1";
@@ -8,9 +9,9 @@ export async function run({ root, config, options, recurse }) {
 
   if (options.dryRun) {
     if (!options.noBuild) {
-      console.log("Command: node engine/cli.mjs render . --renderer react");
+      console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     }
-    console.log(`Command: node engine/output/static-server.mjs ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     console.log(`Chrome inspection URL: ${url}`);
     return 0;
   }

package/engine/commands/pdf.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { CLI_ENTRY, STATIC_SERVER, buildReactPdf, formatNodeScriptCommand } from "./_shared.mjs";
+import { STATIC_SERVER, buildReactPdf, formatNodeScriptCommand, formatOpenPressCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const outputPath = options.output ? path.resolve(root, options.output) : undefined;
@@ -7,7 +7,7 @@ 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: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatOpenPressCommand(["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 { CLI_ENTRY, STATIC_SERVER, formatNodeScriptCommand, runCommand } from "./_shared.mjs";
+import { STATIC_SERVER, formatNodeScriptCommand, formatOpenPressCommand, runCommand } from "./_shared.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const renderer = options.renderer ?? "react";
@@ -12,7 +12,7 @@ export async function run({ root, config, options, recurse }) {
   if (options.dryRun) {
     console.log(`OpenPress preview URL: ${url}`);
     if (!options.noBuild) {
-      console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+      console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     }
     console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     return 0;

package/engine/commands/render.mjs

@@ -1,5 +1,5 @@
 import { exportDocument } from "../document-export.mjs";
-import { runCommand } from "./_shared.mjs";
+import { VITE_CONFIG, formatOpenPressCommand, formatViteCommand, runCommand, viteCommandArgs, workspaceRuntimeEnv } from "./_shared.mjs";
 
 export async function run({ root, options }) {
   const renderer = options.renderer ?? "react";
@@ -8,10 +8,12 @@ export async function run({ root, options }) {
     return 2;
   }
   if (options.dryRun) {
-    console.log("Command: node engine/cli.mjs export .");
-    console.log("Command: npx vite build --config vite.config.ts");
+    console.log(`Command: ${formatOpenPressCommand(["export", "."])}`);
+    console.log(`Command: ${formatViteCommand(root, ["build"])}`);
     return 0;
   }
   await exportDocument(root);
-  return runCommand("npx", ["vite", "build", "--config", "vite.config.ts"], root);
+  return runCommand("node", viteCommandArgs(["build", "--config", VITE_CONFIG]), root, {
+    env: workspaceRuntimeEnv(root),
+  });
 }

package/engine/commands/replace.mjs

@@ -3,7 +3,7 @@ import { replaceSourceText } from "../runtime/source-text-tools.mjs";
 export async function run({ config, options }) {
   const args = replaceArgsFromOptions(options);
   if (!args) {
-    console.error("Usage: node engine/cli.mjs replace [path] <from> <to> [--json] [--apply] [--scope content|all] [--include-code] [--case-sensitive]");
+    console.error("Usage: open-press replace [path] <from> <to> [--json] [--apply] [--scope content|all] [--include-code] [--case-sensitive]");
     return 2;
   }
 

package/engine/commands/search.mjs

@@ -3,7 +3,7 @@ import { searchSourceText } from "../runtime/source-text-tools.mjs";
 export async function run({ config, options }) {
   const query = searchQueryFromOptions(options);
   if (!query) {
-    console.error("Usage: node engine/cli.mjs search [path] <query> [--json] [--scope content|all] [--case-sensitive]");
+    console.error("Usage: open-press search [path] <query> [--json] [--scope content|all] [--case-sensitive]");
     return 2;
   }
 

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,75 @@
+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
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+    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.",
   );
 }