@open-press/cli 0.7.1 → 1.0.0

package/README.md

@@ -2,16 +2,22 @@
 
 Scaffolder for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
 
+## Prerequisite
+
+Node.js 20 or newer with `npm` / `npx`.
+
 ## Quick start
 
 ```bash
-npx @open-press/cli init my-doc --pack editorial-monograph
+npx @open-press/cli init my-doc
 cd my-doc
 npm run dev
 ```
 
 Then open the local URL printed by Vite (typically `http://127.0.0.1:5173/?dev=1`).
 
+The CLI creates the OpenPress runtime workspace only. Starters and examples live in skills, installed separately with `npx skills add <owner/repo>`. The starter-bearing skills in the framework repo are just skills; agents can read and use them directly.
+
 ## Usage
 
 ```
@@ -20,39 +26,49 @@ npx @open-press/cli init <target> [flags]
 
 | Flag                 | Description                                                                 |
 | -------------------- | --------------------------------------------------------------------------- |
-| `--pack <name>`      | Style pack starter: `editorial-monograph` or `claude-document`              |
-| `--title <s>`        | Document title (written to `openpress.config.mjs`)                          |
+| `--title <s>`        | Document title (written to workspace config)                                |
 | `--subtitle <s>`     | Document subtitle                                                           |
 | `--organization <s>` | Organization name                                                           |
 | `--author <s>`       | Author name                                                                 |
-| `--no-git`           | Skip `git init`                                                             |
-| `--no-install`       | Skip `npm install`                                                          |
-| `--force`            | Allow scaffolding into a non-empty target                                   |
+| `--no-git`           | Skip `git init` + initial commit (use when scaffolding inside an existing repo) |
+| `--no-install`       | Skip `npm install` (offline, or you'll run pnpm/bun yourself)              |
 | `--help`             | Print help                                                                  |
 
+> The target must be empty. A `.git/` directory or other harmless dotfiles (`.gitignore`, `.gitkeep`, `.DS_Store`) are ignored — common when scaffolding into a fresh repo.
+
+To use an opinionated starter, install a skill and let the agent read that skill's files:
+
+```bash
+npx -y skills@latest add quan0715/openpress-social-card-skill
+```
+
 ## What it creates
 
 A self-contained workspace with:
 
 - `engine/`, `src/`, `vite.config.ts` — the open-press framework (snapshot of `@open-press/core`)
-- `document/` — your content (populated from the chosen style pack)
 - `.claude/skills/` and `.agents/skills/` — agent skill files for Claude Code, Codex, Cursor, Copilot, etc.
 - `openpress.config.mjs` — workspace metadata (title, subtitle, organization, author)
 - `AGENTS.md` — agent contract
 
+The `press/` or transitional `document/` source tree is added by a skill, user-authored code, or a project-specific workflow after init.
+
 ## After init
 
 Workspace commands (run via `npm run` or `node engine/cli.mjs`):
 
 ```
-npm run dev         # start workbench
-npm run build       # render production output (dist-react/)
-npm run preview     # preview production build
-npm run openpress:validate   # structural checks
-npm run openpress:pdf        # render PDF
-npm run openpress:deploy:dry-run
+npm run dev                       # start workbench
+npm run build                     # validate + render dist-react/
+npm run preview                   # preview production build
+npm run typecheck                 # tsc --noEmit
+npm run openpress:image           # render one PNG per page
+npm run openpress:pdf             # render PDF
+npm run openpress:deploy:dry-run  # preview deploy without publishing
 ```
 
+Full reference: <https://open-press.dev/docs/cli>
+
 ## License
 
 MIT — see [LICENSE](https://github.com/quan0715/open-press/blob/main/LICENSE).

package/dist/cli.js

@@ -6,61 +6,21 @@ import process2 from "process";
 // src/init.ts
 import { spawn } from "child_process";
 import { existsSync } from "fs";
-import { cp, mkdir as mkdir2, rm as rm2 } from "fs/promises";
-import path2 from "path";
+import { cp, mkdir } from "fs/promises";
+import path from "path";
 import process from "process";
 import { fileURLToPath } from "url";
 
-// src/degit.ts
-import { createWriteStream } from "fs";
-import { mkdir, rm, stat } from "fs/promises";
-import { tmpdir } from "os";
-import path from "path";
-import { Readable } from "stream";
-import { pipeline } from "stream/promises";
-import { x as extract } from "tar";
-async function degit({ owner, repo, ref = "main", dest, subdir }) {
-  const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/${ref}`;
-  const tmpDir = await mkdir(path.join(tmpdir(), `open-press-degit-${Date.now()}`), { recursive: true });
-  const tarballPath = path.join(tmpDir, "repo.tar.gz");
-  try {
-    await fetchTo(url, tarballPath);
-    await mkdir(dest, { recursive: true });
-    const subdirSegments = subdir ? subdir.split("/").filter(Boolean).length : 0;
-    const totalStrip = 1 + subdirSegments;
-    const filterPrefix = subdir ? subdir.replace(/\/$/, "") + "/" : null;
-    await extract({
-      file: tarballPath,
-      cwd: dest,
-      strip: totalStrip,
-      filter: (filePath) => {
-        const segments = filePath.split("/");
-        const inside = segments.slice(1).join("/");
-        if (filterPrefix) {
-          return inside.startsWith(filterPrefix);
-        }
-        return true;
-      }
-    });
-  } finally {
-    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
-    });
-  }
-}
-async function fetchTo(url, destFile) {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok || !res.body) {
-    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
-  }
-  await pipeline(Readable.fromWeb(res.body), createWriteStream(destFile));
-}
-async function pathIsEmpty(target) {
+// src/path-is-empty.ts
+import { readdir, stat } from "fs/promises";
+var HARMLESS_TARGET_ENTRIES = /* @__PURE__ */ new Set([".git", ".gitignore", ".gitkeep", ".DS_Store"]);
+async function pathIsEmpty(target, options = {}) {
   try {
     const s = await stat(target);
     if (!s.isDirectory()) return false;
-    const { readdir } = await import("fs/promises");
     const entries = await readdir(target);
-    return entries.length === 0;
+    if (!options.ignoreHarmless) return entries.length === 0;
+    return entries.every((entry) => HARMLESS_TARGET_ENTRIES.has(entry));
   } catch {
     return true;
   }
@@ -68,20 +28,17 @@ async function pathIsEmpty(target) {
 
 // src/metadata.ts
 import { readFile, writeFile } from "fs/promises";
-async function patchOpenpressConfig(configPath, patch) {
-  let source = await readFile(configPath, "utf8");
-  for (const [key, value] of Object.entries(patch)) {
-    if (value === void 0 || value === null || value === "") continue;
-    const escaped = escapeStringForJs(value);
-    const re = new RegExp(`(${key}\\s*:\\s*)("[^"]*"|'[^']*'|\`[^\`]*\`)`, "m");
-    if (re.test(source)) {
-      source = source.replace(re, `$1"${escaped}"`);
-    } else {
-      source = source.replace(/(export\s+default\s*\{)/, `$1
-  ${key}: "${escaped}",`);
-    }
+async function patchPressTitle(entryPath, title) {
+  const source = await readFile(entryPath, "utf8");
+  const escaped = escapeStringForJs(title);
+  const existing = /(<Press\b[^>]*\btitle\s*=\s*)("[^"]*"|'[^']*'|\{`[^`]*`\})/;
+  let next;
+  if (existing.test(source)) {
+    next = source.replace(existing, `$1"${escaped}"`);
+  } else {
+    next = source.replace(/<Press\b/, `<Press title="${escaped}"`);
   }
-  await writeFile(configPath, source);
+  await writeFile(entryPath, next);
 }
 function escapeStringForJs(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -115,69 +72,27 @@ async function patchPackageJsonName(packagePath, newName) {
 }
 
 // src/init.ts
-var BUNDLED_PACKS = ["editorial-monograph", "claude-document", "academic-paper"];
 var FRAMEWORK_SKILLS_SOURCE = "quan0715/open-press";
-var __dirname = path2.dirname(fileURLToPath(import.meta.url));
-var TEMPLATE_ROOT = path2.resolve(__dirname, "..", "template");
-var TEMPLATE_CORE = path2.join(TEMPLATE_ROOT, "core");
-var TEMPLATE_PACKS = path2.join(TEMPLATE_ROOT, "packs");
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var TEMPLATE_ROOT = path.resolve(__dirname, "..", "template");
+var TEMPLATE_CORE = path.join(TEMPLATE_ROOT, "core");
 async function init(options) {
-  const packSpec = options.pack ? parsePackSpec(options.pack) : null;
   ensureTemplateBundled();
-  const target = path2.resolve(process.cwd(), options.target);
-  await ensureTarget(target, options.force);
+  const target = path.resolve(process.cwd(), options.target);
+  await ensureTarget(target);
   log(`Creating open-press workspace at ${target}`);
   log("Copying framework (engine + runtime + config)\u2026");
   await cp(TEMPLATE_CORE, target, { recursive: true });
-  const docDest = path2.join(target, "document");
-  await rm2(docDest, { recursive: true, force: true });
-  await mkdir2(docDest, { recursive: true });
-  if (packSpec?.kind === "bundled") {
-    log(`Applying bundled style pack: ${packSpec.name}`);
-    const packStarter = path2.join(TEMPLATE_PACKS, packSpec.name, "document");
-    if (!existsSync(packStarter)) {
-      throw new Error(`Bundled style pack starter not found: ${packStarter}`);
-    }
-    await cp(packStarter, docDest, { recursive: true });
-  } else if (packSpec?.kind === "github") {
-    log(`Fetching style pack from github:${packSpec.owner}/${packSpec.repo}${packSpec.ref ? `#${packSpec.ref}` : ""}\u2026`);
-    try {
-      await degit({
-        owner: packSpec.owner,
-        repo: packSpec.repo,
-        ref: packSpec.ref,
-        dest: docDest,
-        subdir: "starter/document"
-      });
-    } catch (err) {
-      throw new Error(
-        `Failed to fetch pack from github:${packSpec.owner}/${packSpec.repo}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-    if (await pathIsEmpty(docDest)) {
-      throw new Error(
-        `github:${packSpec.owner}/${packSpec.repo} doesn't contain starter/document/ at the repo root.
-Third-party pack repos should follow this layout:
-  <repo>/
-  \u251C\u2500\u2500 starter/
-  \u2502   \u2514\u2500\u2500 document/   \u2190 cli copies this into your workspace's document/
-  \u2514\u2500\u2500 skills/<pack>/SKILL.md   \u2190 npx skills add picks this up`
-      );
-    }
-  }
-  const pkgPath = path2.join(target, "package.json");
+  const pkgPath = path.join(target, "package.json");
   if (existsSync(pkgPath)) {
-    await patchPackageJsonName(pkgPath, path2.basename(target));
+    await patchPackageJsonName(pkgPath, path.basename(target));
   }
-  const configPath = path2.join(target, "openpress.config.mjs");
-  if (existsSync(configPath) && hasMetadata(options)) {
-    log("Writing metadata into openpress.config.mjs");
-    await patchOpenpressConfig(configPath, {
-      title: options.title,
-      subtitle: options.subtitle,
-      organization: options.organization,
-      author: options.author
-    });
+  if (options.title) {
+    const pressEntry = path.join(target, "press", "index.tsx");
+    if (existsSync(pressEntry)) {
+      log("Writing title into <Press> in press/index.tsx");
+      await patchPressTitle(pressEntry, options.title);
+    }
   }
   log(`Installing framework skills via \`npx skills add ${FRAMEWORK_SKILLS_SOURCE}\`\u2026`);
   try {
@@ -186,16 +101,6 @@ Third-party pack repos should follow this layout:
     log(`(framework skills install failed; retry: npx skills add ${FRAMEWORK_SKILLS_SOURCE})`);
     log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
   }
-  if (packSpec?.kind === "github") {
-    const packSource = `${packSpec.owner}/${packSpec.repo}`;
-    log(`Installing pack skills via \`npx skills add ${packSource}\`\u2026`);
-    try {
-      await runInTarget(target, "npx", ["-y", "skills@latest", "add", packSource]);
-    } catch (err) {
-      log(`(pack skills install failed; retry: npx skills add ${packSource})`);
-      log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
   if (options.install) {
     log("Installing dependencies (npm install)\u2026");
     await runInTarget(target, "npm", ["install"]);
@@ -216,46 +121,24 @@ Third-party pack repos should follow this layout:
   }
   printNextSteps(target, options);
 }
-function parsePackSpec(spec) {
-  if (spec.startsWith("github:")) {
-    const rest = spec.slice("github:".length);
-    const [pathPart, ref] = rest.split("#");
-    const segments = pathPart.split("/").filter(Boolean);
-    if (segments.length !== 2) {
-      throw new Error(
-        `Invalid --pack spec: "${spec}". Use github:owner/repo or github:owner/repo#ref.`
-      );
-    }
-    const [owner, repo] = segments;
-    return { kind: "github", owner, repo, ref: ref?.trim() || void 0 };
-  }
-  if (!BUNDLED_PACKS.includes(spec)) {
-    throw new Error(
-      `Unknown style pack: "${spec}". Bundled packs: ${BUNDLED_PACKS.join(", ")}. For third-party packs use github:owner/repo (e.g. github:quan0715/openpress-pack-nycu-thesis).`
-    );
-  }
-  return { kind: "bundled", name: spec };
-}
 function ensureTemplateBundled() {
-  if (!existsSync(TEMPLATE_CORE) || !existsSync(TEMPLATE_PACKS)) {
+  if (!existsSync(TEMPLATE_CORE)) {
     throw new Error(
       `Template not bundled at ${TEMPLATE_ROOT}. If running from source, run \`pnpm sync:template\` in packages/cli first.`
     );
   }
 }
-async function ensureTarget(target, force) {
+async function ensureTarget(target) {
   if (existsSync(target)) {
-    if (force) return;
-    const empty = await pathIsEmpty(target);
+    const empty = await pathIsEmpty(target, { ignoreHarmless: true });
     if (!empty) {
-      throw new Error(`Target ${target} is not empty. Pass --force to scaffold into it anyway.`);
+      throw new Error(
+        `Target ${target} is not empty. Remove existing files first, or scaffold into a different directory.`
+      );
     }
     return;
   }
-  await mkdir2(target, { recursive: true });
-}
-function hasMetadata(options) {
-  return Boolean(options.title || options.subtitle || options.organization || options.author);
+  await mkdir(target, { recursive: true });
 }
 async function runInTarget(cwd, command, args, opts = {}) {
   return new Promise((resolve, reject) => {
@@ -276,7 +159,7 @@ function log(message) {
 `);
 }
 function printNextSteps(target, options) {
-  const rel = path2.relative(process.cwd(), target) || ".";
+  const rel = path.relative(process.cwd(), target) || ".";
   const lines = [
     "",
     "\u2713 Done. Your open-press workspace is ready.",
@@ -297,7 +180,7 @@ function printNextSteps(target, options) {
     "Agent skills installed under .agents/skills/ (universal \u2014 read by Claude Code,",
     `Cursor, Codex, Gemini CLI, etc.). Update later with: npx skills upgrade`,
     "",
-    "Edit content under document/chapters/, or ask your AI agent to help.",
+    "Use an OpenPress-ready skill to add or adapt the press/document source tree.",
     ""
   );
   process.stdout.write(lines.join("\n"));
@@ -310,28 +193,14 @@ Usage:
   npx @open-press/cli init <target> [flags]
 
 Flags:
-  --pack <spec>            Style pack source. Either:
-                             \u2022 a bundled name \u2014 editorial-monograph | claude-document | academic-paper
-                             \u2022 github:owner/repo (third-party pack)
-                             \u2022 github:owner/repo#branch-or-tag
-  --title <s>              Document title (written to openpress.config.mjs)
-  --subtitle <s>           Document subtitle
-  --organization <s>       Organization name
-  --author <s>             Author name
+  --title <s>              Document title (written into <Press title="..."> in press/index.tsx)
   --no-git                 Skip git init
   --no-install             Skip npm install
-  --force                  Allow non-empty target
   --help                   Show this help
 
 Examples:
-  # Bundled
-  npx @open-press/cli init my-doc --pack editorial-monograph
-  npx @open-press/cli init my-brief --pack claude-document --title "Q2 Brief" --author Quan
-  npx @open-press/cli init my-paper --pack academic-paper --title "Paper Title" --author "First Author"
-
-  # Third-party (any GitHub repo with starter/document/ at the root)
-  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
-  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
+  npx @open-press/cli init my-doc
+  npx @open-press/cli init my-brief --title "Q2 Brief"
 `;
 async function main(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
@@ -368,33 +237,16 @@ function parseInitArgs(args) {
   }
   const options = {
     target: "",
-    pack: void 0,
     title: void 0,
-    subtitle: void 0,
-    organization: void 0,
-    author: void 0,
     git: true,
-    install: true,
-    force: false
+    install: true
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     switch (arg) {
-      case "--pack":
-        options.pack = args[++i];
-        break;
       case "--title":
         options.title = args[++i];
         break;
-      case "--subtitle":
-        options.subtitle = args[++i];
-        break;
-      case "--organization":
-        options.organization = args[++i];
-        break;
-      case "--author":
-        options.author = args[++i];
-        break;
       case "--no-git":
         options.git = false;
         break;
@@ -407,9 +259,6 @@ function parseInitArgs(args) {
       case "--install":
         options.install = true;
         break;
-      case "--force":
-        options.force = true;
-        break;
       default:
         if (arg.startsWith("--")) {
           process2.stderr.write(`Unknown flag: ${arg}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.7.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Scaffolder for open-press — AI-first fixed-layout document workspaces.",
   "license": "MIT",
@@ -40,9 +40,7 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "tar": "^7.5.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^25.8.0",
     "tsup": "^8.5.0",
@@ -52,6 +50,7 @@
     "sync:template": "node scripts/sync-template.mjs",
     "build": "pnpm sync:template && tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && node --test tests/*.test.mjs"
   }
 }

package/template/core/AGENTS.md

@@ -16,15 +16,19 @@ will rewrite it.
 
 ```bash
 npm run dev                  # workbench at http://127.0.0.1:5173/?dev=1
-npm run openpress:validate   # structural checks
-npm run openpress:render     # full render through chromium
+npm run build                # validate + render dist-react/
+npm run openpress:image      # write dist-react/images/page-*.png
 npm run openpress:pdf        # write document.pdf
-npm run openpress:export     # write public/openpress/document.json
 npm run openpress:deploy     # deploy via the configured adapter
 npx open-press doctor        # current vs latest version + pending migrations
 npx open-press upgrade       # apply the upgrade flow (see below)
 ```
 
+The intermediate engine steps live behind `node engine/cli.mjs` if you
+need them directly (rarely): `validate` (source-level checks only,
+fast), `export` (write `public/openpress/document.json` without
+bundling), `inspect` (post-render geometry + comment markers).
+
 ## When the user asks to upgrade
 
 Triggers: "升級 / 套件更新 / upgrade open-press / apply latest design /
@@ -44,8 +48,7 @@ update to vX.Y.Z" etc.
    Apply to `document/` with user confirmation.
 5. Verify:
    ```bash
-   npm run openpress:validate
-   npm run openpress:render
+   npm run build
    ```
    Fix anything broken using the migration notes.
 6. Report to the user: starting version → ending version, what was
@@ -73,32 +76,33 @@ regenerate `document.json`. So edits to:
 the change:
 
 ```bash
-npm run openpress:export   # regenerate public/openpress/document.json
+npm run build              # validate + render (includes the export step)
 # then refresh the browser
+# — or, for the inner export only, without the full Vite bundle step:
+node engine/cli.mjs export .
 ```
 
 Quick rules of thumb:
 
 - Pure CSS edits under `document/theme/` that don't move blocks → HMR
   is enough (CSS is hot-replaced).
-- Anything that affects content, pagination, or metadata → re-export.
-- `npm run openpress:render` is `export` + extra asset sync; either
-  works to refresh the JSON.
+- Anything that affects content, pagination, or metadata → re-build (or
+  call `node engine/cli.mjs export .` for just the JSON refresh).
 
 **Agent SOP**: after applying any non-CSS edit to `document/`, run
-`npm run openpress:export` before telling the user "done". If they ask
-"why didn't my change show up?", check whether `document.json` was
+`npm run build` before telling the user "done". If they ask "why
+didn't my change show up?", check whether `document.json` was
 regenerated since the edit.
 
 ## When the user reports a render / paginate issue
 
 Press Tree paginates at build time. Common things to check:
 
-1. `npm run openpress:export` then inspect
+1. `npm run build` then inspect
    `public/openpress/document.json` for `source.warnings` (chain
    overflow, missing chains, etc.).
-2. `npm run openpress:validate` for structural issues
-   (missing entries, broken anchors).
+2. `node engine/cli.mjs validate .` for structural issues
+   (missing entries, broken anchors) — faster than a full build.
 3. `npm run dev` and use the workbench inspector to find which MDX
    block / Frame element is misbehaving — comments and inline
    annotations work directly from there.