@open-press/cli 1.0.0 → 1.1.0

package/template/core/engine/react/pipeline/press-tree.mjs

@@ -1,135 +0,0 @@
-// Layer 2 — Press Tree Expansion.
-//
-// SSR-renders the user's Press tree with a PressContext provider that
-// supplies resolved sources and (optionally) allocation hints. Output:
-//   - rendered HTML (used by Layer 3 for measurement and Layer 5 for final)
-//   - extracted frame metadata (frameKey, role, chrome, sequence position)
-//   - per-frame MdxArea slots (chainId, sequence index within frame)
-//
-// Frames are discovered by parsing the rendered HTML for elements with the
-// `data-openpress-frame-key` attribute. This works because <Frame> renders
-// to a deterministic `<section>` with that attribute set.
-
-import React from "react";
-import { renderToStaticMarkup } from "react-dom/server";
-
-const FRAME_OPEN_RE = /<section\b([^>]*)\bdata-openpress-frame-key="([^"]+)"([^>]*)>/g;
-const ATTR_RE = (name) => new RegExp(`\\b${name}="([^"]*)"`);
-
-/**
- * Render the Press tree and extract frame structure.
- *
- * @param {object} opts
- * @param {React.ComponentType} opts.Press        The user's default-exported Press component.
- * @param {object} opts.PressContext              The PressContext from @open-press/core.
- * @param {Record<string, object>} opts.sources   Resolved sources keyed by sourceId.
- * @param {object|null} opts.hints                Allocation hints (or null on first pass).
- * @param {object|null} opts.allocation           FrameAllocation map (or null for measurement).
- * @returns {{ html: string, frames: Array<FrameInstance> }}
- */
-export function expandPressTree({ Press: UserPress, PressContext, sources, hints = null, allocation = null, toc = null }) {
-  const html = renderToStaticMarkup(
-    React.createElement(
-      PressContext.Provider,
-      { value: { sources, allocation, hints, toc } },
-      React.createElement(UserPress),
-    ),
-  );
-
-  const frames = extractFrames(html);
-  enforceUniqueFrameKeys(frames);
-  return { html, frames };
-}
-
-function extractFrames(html) {
-  const frames = [];
-  let match;
-  FRAME_OPEN_RE.lastIndex = 0;
-  while ((match = FRAME_OPEN_RE.exec(html)) !== null) {
-    const attrsBefore = match[1] ?? "";
-    const frameKey = match[2];
-    const attrsAfter = match[3] ?? "";
-    const allAttrs = `${attrsBefore} ${attrsAfter}`;
-    const role = pickAttr(allAttrs, "data-frame-role") || undefined;
-    const chromeRaw = pickAttr(allAttrs, "data-frame-chrome");
-    const chrome = chromeRaw === "false" ? false : true;
-    const openIndex = match.index;
-    const sectionHtml = sliceSection(html, openIndex);
-    const mdxAreas = extractMdxAreas(sectionHtml);
-    frames.push({
-      frameKey,
-      role,
-      chrome,
-      mdxAreas,
-      htmlStart: openIndex,
-      htmlEnd: openIndex + sectionHtml.length,
-      html: sectionHtml,
-    });
-  }
-  return frames;
-}
-
-const MDX_AREA_RE = /<([a-z][a-z0-9-]*)\b([^>]*)\bdata-openpress-mdx-area="true"([^>]*)>/gi;
-
-function extractMdxAreas(sectionHtml) {
-  const areas = [];
-  let match;
-  MDX_AREA_RE.lastIndex = 0;
-  while ((match = MDX_AREA_RE.exec(sectionHtml)) !== null) {
-    const attrs = `${match[2] ?? ""} ${match[3] ?? ""}`;
-    const chainId = pickAttr(attrs, "data-openpress-mdx-area-chain");
-    const overflow = pickAttr(attrs, "data-openpress-mdx-area-overflow") || "extend";
-    if (!chainId) continue;
-    const indexInFrame = areas.filter((a) => a.chainId === chainId).length;
-    areas.push({ chainId, overflow, indexInFrame, indexAcrossFrame: areas.length });
-  }
-  return areas;
-}
-
-function pickAttr(attrs, name) {
-  const match = ATTR_RE(name).exec(attrs);
-  return match ? match[1] : "";
-}
-
-// Find the end of a <section> opening at `start`, returning the full
-// `<section ...>...</section>` substring. Handles nested <section> elements
-// by depth-counting.
-function sliceSection(html, start) {
-  const sectionOpen = /<section\b[^>]*>/g;
-  const sectionClose = /<\/section\s*>/g;
-  sectionOpen.lastIndex = start + 1;
-  sectionClose.lastIndex = start + 1;
-  let depth = 1;
-  while (depth > 0) {
-    const nextOpen = sectionOpen.exec(html);
-    const nextClose = sectionClose.exec(html);
-    if (!nextClose) {
-      throw new Error(`Unterminated <section> in Press tree HTML near offset ${start}`);
-    }
-    if (nextOpen && nextOpen.index < nextClose.index) {
-      depth += 1;
-      sectionClose.lastIndex = nextOpen.index + 1;
-      continue;
-    }
-    depth -= 1;
-    if (depth === 0) {
-      return html.slice(start, nextClose.index + nextClose[0].length);
-    }
-    sectionOpen.lastIndex = nextClose.index + 1;
-  }
-  throw new Error(`Section depth balance bug at offset ${start}`);
-}
-
-function enforceUniqueFrameKeys(frames) {
-  const seen = new Map();
-  for (const frame of frames) {
-    if (seen.has(frame.frameKey)) {
-      const prior = seen.get(frame.frameKey);
-      throw new Error(
-        `Duplicate frameKey "${frame.frameKey}" found in Press tree. ` +
-          `First seen with role "${prior.role ?? "?"}", second with role "${frame.role ?? "?"}".`,
-      );
-    }
-    seen.set(frame.frameKey, frame);
-  }
-}

package/template/core/engine/react/press-tree-inspection.mjs

@@ -1,172 +0,0 @@
-// Walks the user's default-exported component tree to extract
-// <Workspace> and <Press> metadata declared as JSX props.
-//
-// The 1.0 contract says <Press> carries every per-document setting on
-// its props (title, page, sources, slug, theme, componentsDir) and is
-// always nested inside <Workspace>. This helper invokes the user's
-// component once at load time to inspect those props before the engine
-// runs its render pipeline.
-//
-// Safe to call because Workspace, Press, and (typically) the user's
-// default export are inert function components that just return JSX —
-// they don't use hooks at the entry boundary.
-
-import React from "react";
-
-/**
- * Inspect the user's default export and extract every <Press> child
- * of the (optional) <Workspace> wrapper. The export pipeline iterates
- * the returned `presses` array — single-Press workspaces simply have
- * length 1, multi-Press have length N. There is no separate code path
- * for the single-Press case.
- *
- * @param {object} opts
- * @param {Function} opts.UserComponent  The default export of press/index.tsx.
- * @param {symbol} opts.PRESS_MARKER     Marker identifying Press components.
- * @param {symbol} opts.WORKSPACE_MARKER Marker identifying Workspace components.
- * @returns {{
- *   workspaceProps: Record<string, unknown>,
- *   presses: Array<{
- *     element: object,                          // ReactElement
- *     props: Record<string, unknown>,           // Press JSX props (no children)
- *     metadata: {
- *       title?: string,
- *       page?: unknown,
- *       slug?: string,
- *       theme?: string,
- *       componentsDir?: string,
- *       captionNumbering?: unknown,
- *     },
- *     sources: Record<string, unknown> | null,  // mdxSource() descriptors keyed by id
- *     children: unknown,                        // raw children for re-rendering
- *     index: number,                            // position in the Workspace
- *   }>,
- *   wrappedInWorkspace: boolean,
- * }}
- */
-export function inspectPressTree({ UserComponent, PRESS_MARKER, WORKSPACE_MARKER }) {
-  if (typeof UserComponent !== "function") {
-    return emptyResult();
-  }
-
-  let root;
-  try {
-    root = UserComponent({});
-  } catch (err) {
-    // The user's default export threw before returning JSX. This is rare
-    // (function components at the entry boundary don't normally use hooks
-    // that could fail), but we treat it as "no Press metadata declared"
-    // and let the render pipeline surface the real error later with
-    // full React error context.
-    return emptyResult();
-  }
-
-  if (!isReactElement(root)) return emptyResult();
-
-  const workspaceProps = isMarked(root, WORKSPACE_MARKER) ? extractProps(root) : {};
-  const wrappedInWorkspace = isMarked(root, WORKSPACE_MARKER);
-
-  // Find every <Press> element in the tree (Workspace child, or root itself).
-  const pressElements = collectPressElements(root, PRESS_MARKER);
-
-  const presses = pressElements.map((element, index) => {
-    const props = extractProps(element);
-    return {
-      element,
-      props,
-      metadata: pickPressMetadata(props),
-      sources: extractSources(props),
-      children: element.props?.children ?? null,
-      index,
-    };
-  });
-
-  return {
-    workspaceProps,
-    presses,
-    wrappedInWorkspace,
-  };
-}
-
-function emptyResult() {
-  return {
-    workspaceProps: {},
-    presses: [],
-    wrappedInWorkspace: false,
-  };
-}
-
-function isReactElement(value) {
-  return value && typeof value === "object" && "type" in value && "props" in value;
-}
-
-function isMarked(element, marker) {
-  if (!isReactElement(element)) return false;
-  const type = element.type;
-  if (!type) return false;
-  // Components are tagged via `Component.openpressMarker = MARKER`.
-  return type.openpressMarker === marker;
-}
-
-function extractProps(element) {
-  if (!isReactElement(element) || !element.props) return {};
-  // Drop children — props are non-tree metadata only.
-  const { children, ...rest } = element.props;
-  return rest;
-}
-
-function collectPressElements(root, PRESS_MARKER) {
-  const found = [];
-  walk(root);
-  return found;
-
-  function walk(node) {
-    if (!isReactElement(node)) {
-      // Could be array / fragment / string / number — flatten and recurse.
-      if (Array.isArray(node)) {
-        for (const child of node) walk(child);
-      }
-      return;
-    }
-    if (isMarked(node, PRESS_MARKER)) {
-      found.push(node);
-      // Don't descend into Press — its children are the document tree,
-      // not more workspace structure.
-      return;
-    }
-    // Recurse into children + Fragment-like wrappers.
-    const children = node.props?.children;
-    if (children == null) return;
-    React.Children.forEach(children, walk);
-  }
-}
-
-function pickPressMetadata(pressProps) {
-  const out = {};
-  if (typeof pressProps.title === "string") out.title = pressProps.title;
-  if (pressProps.page !== undefined) out.page = pressProps.page;
-  if (typeof pressProps.slug === "string") out.slug = pressProps.slug;
-  if (typeof pressProps.theme === "string") out.theme = pressProps.theme;
-  if (typeof pressProps.componentsDir === "string") out.componentsDir = pressProps.componentsDir;
-  if (pressProps.captionNumbering !== undefined) out.captionNumbering = pressProps.captionNumbering;
-  return out;
-}
-
-// Convert the v1.0 <Press sources={[ mdxSource({ id, ... }), ... ]}> array
-// into the engine's expected sources record { [id]: descriptor }. Returns
-// null if no sources prop was declared (engine falls back to the named
-// `export const sources` from the entry module — the v0.x shape).
-function extractSources(pressProps) {
-  if (!Array.isArray(pressProps.sources)) return null;
-  const out = {};
-  for (const entry of pressProps.sources) {
-    if (!entry || typeof entry !== "object") continue;
-    const id = typeof entry.id === "string" ? entry.id : null;
-    if (!id) continue;
-    // Strip the id field — the engine's descriptor shape doesn't carry it
-    // (id was the record key in v0.x).
-    const { id: _omit, ...descriptor } = entry;
-    out[id] = descriptor;
-  }
-  return out;
-}

package/template/core/engine/react/project-asset-endpoint.d.mts

@@ -1,10 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-
-export function handleProjectAssetRequest(
-  req: IncomingMessage,
-  res: ServerResponse,
-  options?: {
-    root?: string;
-    timestamp?: string;
-  },
-): Promise<void>;

package/template/core/engine/react/project-asset-endpoint.mjs

@@ -1,361 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { loadConfig } from "../runtime/config.mjs";
-import { collectSourceTextFiles } from "../runtime/source-text-tools.mjs";
-import { insertCommentMarker } from "./comment-marker.mjs";
-import { readJsonBody, writeJson } from "./http-json.mjs";
-
-export async function handleProjectAssetRequest(req, res, {
-  root = ".",
-  timestamp = undefined,
-} = {}) {
-  if (req.method !== "POST") {
-    writeJson(res, 405, { ok: false, message: "OpenPress project asset endpoint requires POST." });
-    return;
-  }
-
-  try {
-    const body = await readJsonBody(req, { bodyLabel: "Project asset request" });
-    const config = await loadConfig(root);
-    const action = stringValue(body?.action);
-    const kind = stringValue(body?.kind);
-    const name = stringValue(body?.name);
-
-    if (kind !== "media" && kind !== "component") {
-      throw new Error("Project asset kind must be `media` or `component`.");
-    }
-    if (!name) throw new Error("Project asset action requires a name.");
-
-    if (action === "rename") {
-      const result = await renameProjectAsset({
-        config,
-        kind,
-        name,
-        nextName: body?.nextName,
-      });
-      writeJson(res, 200, { ok: true, ...result });
-      return;
-    }
-
-    if (action === "delete") {
-      const result = await deleteProjectAsset({ config, kind, name });
-      const status = result.needsReferenceCleanup ? 409 : 200;
-      writeJson(res, status, { ok: !result.needsReferenceCleanup, ...result });
-      return;
-    }
-
-    if (action === "comment") {
-      const result = await createProjectAssetComment({
-        config,
-        kind,
-        name,
-        note: body?.note,
-        commentTarget: body?.commentTarget,
-        currentSource: body?.currentSource,
-        objectEntity: body?.objectEntity,
-        timestamp,
-      });
-      writeJson(res, 200, { ok: true, ...result });
-      return;
-    }
-
-    throw new Error("Project asset action must be `rename`, `delete`, or `comment`.");
-  } catch (error) {
-    writeJson(res, 400, {
-      ok: false,
-      message: error instanceof Error ? error.message : String(error),
-    });
-  }
-}
-
-async function renameProjectAsset({ config, kind, name, nextName }) {
-  const normalizedCurrentName = normalizeAssetName(kind, name);
-  const normalizedNextName = normalizeAssetName(kind, stringValue(nextName), normalizedCurrentName);
-  if (!normalizedNextName || normalizedNextName === normalizedCurrentName) {
-    throw new Error("Rename requires a different valid name.");
-  }
-
-  const currentPath = resolveAssetPath(config, kind, normalizedCurrentName);
-  const nextPath = resolveAssetPath(config, kind, normalizedNextName);
-  await assertPathExists(currentPath, `${kind} asset not found: ${normalizedCurrentName}`);
-  if (await fileExists(nextPath)) throw new Error(`${kind} asset already exists: ${normalizedNextName}`);
-
-  await fs.rename(currentPath, nextPath);
-  const referenceResult = await replaceProjectAssetReferences({
-    config,
-    kind,
-    from: normalizedCurrentName,
-    to: normalizedNextName,
-  });
-
-  return {
-    action: "rename",
-    kind,
-    name: normalizedCurrentName,
-    nextName: normalizedNextName,
-    referenceCount: referenceResult.referenceCount,
-    fileCount: referenceResult.fileCount,
-  };
-}
-
-async function deleteProjectAsset({ config, kind, name }) {
-  const normalizedName = normalizeAssetName(kind, name);
-  const references = await findProjectAssetReferences({ config, kind, name: normalizedName });
-  if (references.length > 0) {
-    return {
-      action: "delete",
-      kind,
-      name: normalizedName,
-      needsReferenceCleanup: true,
-      referenceCount: references.length,
-      references: references.slice(0, 12),
-      message: `Cannot delete ${kind} asset while ${references.length} reference(s) still exist.`,
-    };
-  }
-
-  const targetPath = resolveAssetPath(config, kind, normalizedName);
-  await assertPathExists(targetPath, `${kind} asset not found: ${normalizedName}`);
-  await fs.rm(targetPath, { recursive: true, force: true });
-
-  return {
-    action: "delete",
-    kind,
-    name: normalizedName,
-    needsReferenceCleanup: false,
-    referenceCount: 0,
-  };
-}
-
-async function createProjectAssetComment({
-  config,
-  kind,
-  name,
-  note,
-  commentTarget,
-  currentSource,
-  objectEntity,
-  timestamp,
-}) {
-  const normalizedName = normalizeAssetName(kind, name);
-  const noteText = stringValue(note);
-  if (!noteText) throw new Error("Project asset comment requires a note.");
-
-  const target = await resolveCommentTarget({
-    config,
-    kind,
-    name: normalizedName,
-    commentTarget: stringValue(commentTarget),
-    currentSource,
-  });
-  const objectHint = stringValue(objectEntity?.id) ? ` object=${stringValue(objectEntity.id)}` : "";
-
-  const result = await insertCommentMarker({
-    root: config.root,
-    path: target.path,
-    source: { line: target.line, column: 1 },
-    note: `${assetLabel(kind, normalizedName)}：${noteText}`,
-    hint: `openpress-project-asset kind=${kind} action=comment target=${target.reason} asset=${normalizedName}${objectHint}`,
-    timestamp,
-  });
-
-  return {
-    action: "comment",
-    kind,
-    name: normalizedName,
-    comment: {
-      id: result.id,
-      timestamp: result.timestamp,
-      path: result.path,
-      line: result.line,
-    },
-  };
-}
-
-async function resolveCommentTarget({ config, kind, name, commentTarget, currentSource }) {
-  if (commentTarget === "current-page") {
-    const currentPath = stringValue(currentSource?.path);
-    if (currentPath) {
-      return {
-        path: currentPath,
-        line: normalizePositiveInteger(currentSource?.line) ?? 1,
-        reason: "current-page",
-      };
-    }
-  }
-
-  const references = await findProjectAssetReferences({ config, kind, name });
-  const preferred = references.find((reference) => {
-    if (kind === "component") return reference.preview.includes("data-openpress-component");
-    return reference.path.includes("/content/") || reference.path.endsWith(".mdx");
-  }) ?? references[0];
-  if (!preferred) {
-    throw new Error(`No editable reference found for ${kind} asset: ${name}`);
-  }
-  return {
-    path: preferred.path,
-    line: preferred.line,
-    reason: "asset-reference",
-  };
-}
-
-async function replaceProjectAssetReferences({ config, kind, from, to }) {
-  const replacements = replacementPairs(kind, from, to);
-  const files = await collectSourceTextFiles(config, { scope: "all" });
-  let referenceCount = 0;
-  let fileCount = 0;
-
-  for (const file of files) {
-    let text = file.text;
-    let changed = false;
-    for (const [fromText, toText] of replacements) {
-      if (!fromText || fromText === toText || !text.includes(fromText)) continue;
-      const count = text.split(fromText).length - 1;
-      text = text.split(fromText).join(toText);
-      referenceCount += count;
-      changed = true;
-    }
-    if (!changed) continue;
-    fileCount += 1;
-    await fs.writeFile(file.absolutePath, text, "utf8");
-  }
-
-  return { referenceCount, fileCount };
-}
-
-async function findProjectAssetReferences({ config, kind, name }) {
-  const tokens = referenceTokens(kind, name);
-  const files = await collectSourceTextFiles(config, { scope: "all" });
-  const references = [];
-
-  for (const file of files) {
-    const lines = file.text.split(/\r?\n/);
-    lines.forEach((line, index) => {
-      if (!tokens.some((token) => token && line.includes(token))) return;
-      references.push({
-        path: file.relativePath,
-        line: index + 1,
-        preview: line.trim().slice(0, 180),
-      });
-    });
-  }
-
-  return references;
-}
-
-function resolveAssetPath(config, kind, name) {
-  const root = kind === "media" ? config.paths.mediaDir : config.paths.componentsDir;
-  const target = path.resolve(root, name);
-  const resolvedRoot = path.resolve(root);
-  if (!target.startsWith(`${resolvedRoot}${path.sep}`) && target !== resolvedRoot) {
-    throw new Error(`Project asset path escapes ${kind} directory: ${name}`);
-  }
-  return target;
-}
-
-function normalizeAssetName(kind, value, currentName = "") {
-  if (kind === "media") return sanitizeMediaFileName(value, currentName);
-  return sanitizeComponentName(value);
-}
-
-function sanitizeMediaFileName(value, currentName = "") {
-  const rawName = stringValue(value);
-  if (!rawName) return "";
-  const currentExt = path.extname(currentName);
-  const suppliedExt = path.extname(rawName);
-  const baseName = path.basename(suppliedExt ? rawName : `${rawName}${currentExt}`).trim();
-  if (!baseName) return "";
-  const ext = path.extname(baseName);
-  const stem = path.basename(baseName, ext)
-    .replace(/[\\/:*?"<>|#%{}^~[\]`]/g, "-")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "");
-  if (!stem || !ext || !isAllowedMediaFile(`${stem}${ext}`)) return "";
-  return `${stem}${ext.toLowerCase()}`;
-}
-
-function sanitizeComponentName(value) {
-  const raw = stringValue(value).replaceAll("\\", "/").split("/").pop() ?? "";
-  const normalized = raw
-    .trim()
-    .replace(/\s+/g, "-")
-    .replace(/[^a-zA-Z0-9_-]/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "");
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(normalized)) return "";
-  return normalized;
-}
-
-function isAllowedMediaFile(fileName) {
-  return /\.(png|jpe?g|gif|svg|webp)$/i.test(fileName);
-}
-
-function replacementPairs(kind, from, to) {
-  if (kind === "media") {
-    return uniquePairs([
-      [from, to],
-      [encodeURIComponent(from), encodeURIComponent(to)],
-      [`@media/${from}`, `@media/${to}`],
-    ]);
-  }
-  return uniquePairs([
-    [from, to],
-    [`@component/${from}`, `@component/${to}`],
-  ]);
-}
-
-function referenceTokens(kind, name) {
-  if (kind === "media") {
-    return uniqueValues([
-      name,
-      encodeURIComponent(name),
-      `@media/${name}`,
-    ]);
-  }
-  return uniqueValues([
-    name,
-    `@component/${name}`,
-    `data-openpress-component="${name}"`,
-    `data-openpress-component='${name}'`,
-  ]);
-}
-
-function uniquePairs(pairs) {
-  const seen = new Set();
-  return pairs.filter(([from, to]) => {
-    const key = `${from}\0${to}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
-function uniqueValues(values) {
-  return Array.from(new Set(values.filter(Boolean)));
-}
-
-function assetLabel(kind, name) {
-  return kind === "media" ? `Media ${name}` : `Component ${name}`;
-}
-
-function stringValue(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizePositiveInteger(value) {
-  const number = Number(value);
-  return Number.isInteger(number) && number > 0 ? number : null;
-}
-
-async function assertPathExists(filePath, message) {
-  if (!(await fileExists(filePath))) throw new Error(message);
-}
-
-async function fileExists(filePath) {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}