@open-press/cli 0.3.0 → 0.6.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import process2 from "process";
 // src/init.ts
 import { spawn } from "child_process";
 import { existsSync } from "fs";
-import { cp, mkdir as mkdir2, readdir, rm as rm2 } from "fs/promises";
+import { cp, mkdir as mkdir2, rm as rm2 } from "fs/promises";
 import path2 from "path";
 import process from "process";
 import { fileURLToPath } from "url";
@@ -19,12 +19,47 @@ 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) {
   try {
     const s = await stat(target);
     if (!s.isDirectory()) return false;
-    const { readdir: readdir2 } = await import("fs/promises");
-    const entries = await readdir2(target);
+    const { readdir } = await import("fs/promises");
+    const entries = await readdir(target);
     return entries.length === 0;
   } catch {
     return true;
@@ -80,13 +115,14 @@ async function patchPackageJsonName(packagePath, newName) {
 }
 
 // src/init.ts
-var KNOWN_PACKS = ["editorial-monograph", "claude-document"];
+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_SKILLS = path2.join(TEMPLATE_ROOT, "skills");
+var TEMPLATE_PACKS = path2.join(TEMPLATE_ROOT, "packs");
 async function init(options) {
-  validatePack(options.pack);
+  const packSpec = options.pack ? parsePackSpec(options.pack) : null;
   ensureTemplateBundled();
   const target = path2.resolve(process.cwd(), options.target);
   await ensureTarget(target, options.force);
@@ -94,20 +130,41 @@ async function init(options) {
   log("Copying framework (engine + runtime + config)\u2026");
   await cp(TEMPLATE_CORE, target, { recursive: true });
   const docDest = path2.join(target, "document");
-  if (options.pack) {
-    log(`Applying style pack: ${options.pack}`);
-    await rm2(docDest, { recursive: true, force: true });
-    await mkdir2(docDest, { recursive: true });
-    const packStarter = path2.join(TEMPLATE_SKILLS, options.pack, "starter", "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(`Style pack starter not found: ${packStarter}`);
+      throw new Error(`Bundled style pack starter not found: ${packStarter}`);
     }
     await cp(packStarter, docDest, { recursive: true });
-  } else {
-    await mkdir2(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`
+      );
+    }
   }
-  log("Installing SKILL files\u2026");
-  await installSkills(target);
   const pkgPath = path2.join(target, "package.json");
   if (existsSync(pkgPath)) {
     await patchPackageJsonName(pkgPath, path2.basename(target));
@@ -122,6 +179,23 @@ async function init(options) {
       author: options.author
     });
   }
+  log(`Installing framework skills via \`npx skills add ${FRAMEWORK_SKILLS_SOURCE}\`\u2026`);
+  try {
+    await runInTarget(target, "npx", ["-y", "skills@latest", "add", FRAMEWORK_SKILLS_SOURCE]);
+  } catch (err) {
+    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"]);
@@ -142,44 +216,33 @@ async function init(options) {
   }
   printNextSteps(target, options);
 }
-async function installSkills(target) {
-  const skillDirs = await readdir(TEMPLATE_SKILLS, { withFileTypes: true });
-  const claudeRoot = path2.join(target, ".claude", "skills");
-  const agentsRoot = path2.join(target, ".agents", "skills");
-  await mkdir2(claudeRoot, { recursive: true });
-  await mkdir2(agentsRoot, { recursive: true });
-  for (const dir of skillDirs) {
-    if (!dir.isDirectory()) continue;
-    const source = path2.join(TEMPLATE_SKILLS, dir.name);
-    const claudeTarget = path2.join(claudeRoot, dir.name);
-    const agentsTarget = path2.join(agentsRoot, dir.name);
-    await copySkillFiles(source, claudeTarget);
-    await copySkillFiles(source, agentsTarget);
+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 };
   }
-}
-async function copySkillFiles(source, dest) {
-  await mkdir2(dest, { recursive: true });
-  const entries = await readdir(source, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.name === "starter" || entry.name === "agents") continue;
-    const from = path2.join(source, entry.name);
-    const to = path2.join(dest, entry.name);
-    await cp(from, to, { recursive: true });
+  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_SKILLS)) {
+  if (!existsSync(TEMPLATE_CORE) || !existsSync(TEMPLATE_PACKS)) {
     throw new Error(
       `Template not bundled at ${TEMPLATE_ROOT}. If running from source, run \`pnpm sync:template\` in packages/cli first.`
     );
   }
 }
-function validatePack(pack) {
-  if (pack === void 0) return;
-  if (!KNOWN_PACKS.includes(pack)) {
-    throw new Error(`Unknown style pack: ${pack}. Known packs: ${KNOWN_PACKS.join(", ")}`);
-  }
-}
 async function ensureTarget(target, force) {
   if (existsSync(target)) {
     if (force) return;
@@ -216,7 +279,7 @@ function printNextSteps(target, options) {
   const rel = path2.relative(process.cwd(), target) || ".";
   const lines = [
     "",
-    "\u2713 Done! Your open-press workspace is ready.",
+    "\u2713 Done. Your open-press workspace is ready.",
     "",
     "Next steps:",
     `  cd ${rel}`
@@ -229,9 +292,11 @@ function printNextSteps(target, options) {
     "  # start the workbench:",
     "  npm run dev",
     "",
-    "Then open the local URL printed by vite (typically http://127.0.0.1:5173/?dev=1).",
+    "Then open the local URL printed by Vite (typically http://127.0.0.1:5173/?dev=1).",
+    "",
+    "Agent skills installed under .agents/skills/ (universal \u2014 read by Claude Code,",
+    `Cursor, Codex, Gemini CLI, etc.). Update later with: npx skills upgrade`,
     "",
-    "AI agent skills are installed under .claude/skills/ and .agents/skills/.",
     "Edit content under document/chapters/, or ask your AI agent to help.",
     ""
   );
@@ -245,19 +310,28 @@ Usage:
   npx @open-press/cli init <target> [flags]
 
 Flags:
-  --pack <name>            Style pack starter: editorial-monograph | claude-document
+  --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 (defaults to git user.name)
+  --author <s>             Author name
   --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-doc --pack claude-document --title "Q2 Brief" --author Quan
+  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
 `;
 async function main(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Scaffolder for open-press — AI-first fixed-layout document workspaces.",
   "license": "MIT",

package/template/core/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @open-press/core
 
+## 0.6.0
+
+### Minor Changes
+
+- f8fdecd: Third bundled pack: `academic-paper`.
+
+  A single-column A4 academic / research paper starter — serif title block, abstract band, index terms, numbered sections (I, II, III), italic sub-sections (A, B, C), `[N]` numeric references, sample chapters derived from the IEEE conference template structure (Introduction, Methods, Results & Discussion, Acknowledgment, References).
+
+  ```bash
+  npx @open-press/cli init my-paper --pack academic-paper
+  ```
+
+  Suitable for: draft / preprint / iteration. Not suitable for camera-ready IEEE / ACM submission — those still need LaTeX with the publisher's class file.
+
+  Two-column body and other paged-document features (footnotes, cross-references with page numbers, running headers) are intentionally **out of scope for this release**. They'll be designed as a self-maintained engine evolution + multi-mode architecture in a separate spec round, rather than depending on a third-party pagination polyfill.
+
+- c490653: `@open-press/cli init` accepts third-party style packs via `--pack github:owner/repo`.
+
+  ```bash
+  # bundled (unchanged)
+  npx @open-press/cli init my-doc --pack editorial-monograph
+
+  # third-party (new)
+  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
+  ```
+
+  The cli fetches `starter/document/` from the named repo (default branch, or `#ref` for a specific branch/tag) and copies it into the new workspace. If the pack repo also publishes SKILL files at `skills/<name>/`, they're installed via `npx skills add <owner>/<repo>` after the framework skills, so the agent picks them up automatically.
+
+  Repo layout convention for third-party packs is documented in `docs/style-pack-authoring.md`. Empty-result extraction (the named repo exists but has no `starter/document/` at root) fails with a clear error pointing at the expected layout.
+
+  The two bundled packs (`editorial-monograph`, `claude-document`) keep their current short-name behaviour; only the cli's validator widened to accept the `github:` prefix.
+
+## 0.5.0
+
+### Minor Changes
+
+- 0169cba: Agent-driven upgrade flow.
+
+  **New commands:**
+  - `npx open-press doctor` — diagnose workspace against latest framework state. Reports `@open-press/core` version vs npm latest, installed skill count, and any pending `docs/migrations/<version>.md` notes between current and latest. `--json` for machine-readable output, `--no-cache` to bypass the 24h cache. Always exits 0 (informational only).
+
+  - `npx open-press upgrade` — orchestrate the upgrade. Runs `npm update @open-press/core` (when the workspace declares the dep) and `npx skills upgrade`, then surfaces the list of migration notes for the agent to read. **Does not auto-edit `document/` content** — the agent reads the surfaced `docs/migrations/<version>.md` notes and proposes edits to the user with confirmation. Use `--dry-run` to preview, `--no-deps` / `--no-skills` to target one layer.
+
+  **Dev startup notice:**
+
+  `open-press dev` now runs `doctor` before starting Vite. When the workspace is behind, a single line prints: `○ open-press: @open-press/core 0.4.0 → 0.5.0 · 1 migration note(s) — run npx open-press doctor for details.` Cached for 24h, network failure is silent, never blocks dev.
+
+  **Migration docs:**
+  - New `docs/migrations/_template.md` — each release with breaking changes ships a `docs/migrations/<version>.md` file with sections the agent reads.
+  - New `docs/migrations/0.4.0.md` — backfilled. Documents the SKILL fold (no document or CLI changes).
+
+  **SKILL update:**
+
+  `openpress` skill's "Updating An Existing Workspace" section rewritten around the new commands: detect (`doctor`), apply (`upgrade`), interpret migration notes, propose document edits with user confirmation. Concrete agent workflow + breaking-change reference table.
+
+### Patch Changes
+
+- 931d4ac: Support framework root dogfood workspaces and correct CLI script paths outside the core package root.
+
+## 0.4.0
+
+### Minor Changes
+
+- 3cb4939: Consolidate internal skills (13 → 11).
+  - `openpress-update` folded into `openpress` as an "Updating An Existing Workspace" section. The release-upgrade flow, pre-flight checks, breaking-change reference, and do-not list are now part of the system-operation skill where they naturally belong.
+  - `openpress-document-hierarchy` folded into `openpress-writing` as a "Hierarchy" section. Hierarchy decisions (H2/H3/H4 model, TOC depth, appendix placement, H4 granularity) and prose decisions happen in the same workflow; one skill, one routing decision.
+  - `references/data-structures-outline.md` moved from the hierarchy skill into `openpress-writing/references/`.
+
+  Lower maintenance surface: 2 fewer SKILL.md files to keep in sync, ~5 fewer cross-references to police. No content lost — same rules, fewer files.
+
+  User impact: agents already in workspaces with `openpress-update` or `openpress-document-hierarchy` SKILL files installed should run `npx skills upgrade` to refresh the catalog.
+
 ## 0.3.0
 
 ### Minor Changes

package/template/core/engine/cli.mjs

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

package/template/core/engine/commands/_shared.mjs

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

package/template/core/engine/commands/deploy.mjs

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

package/template/core/engine/commands/dev.mjs

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