perf(packages/core,packages/cli): incremental sync engine

[zrosenbauer]

Summary

• Incremental sync engine: mtime-based page skip, parallel page/asset copy, OpenAPI spec caching, structural change detection — only processes what changed instead of full sync each pass
• CLI build system migration: switched from rslib to kidd (tsdown-based) with React/Ink TUI dev screen
• Dev TUI fixes: replace broken ASCII banner with ink-big-text + ink-gradient, fix "q" hotkey not exiting
• Sidebar build fix: pre-create directories referenced in root _meta.json to prevent Rspress ENOENT crash on empty sections

Changes

• @zpress/core: incremental sync engine (minor), sidebar dir creation fix (patch)
• @zpress/cli: kidd build migration (minor), dev TUI banner + quit fix (patch)

Test plan

• Run zpress dev and verify styled banner renders correctly
• Press q to confirm the dev server exits cleanly
• Run zpress build on a project with empty section directories
• Verify incremental sync skips unchanged files on subsequent passes
• Confirm pnpm check passes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
oss-zpress	Ready	Preview, Comment	Apr 8, 2026 3:52pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 47e5c2a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@zpress/cli	Minor
@zpress/core	Minor
@zpress/kit	Patch
@zpress/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: eb38bb5a-7cd4-41f5-89fe-ab9cc9afc3e7

📥 Commits

Reviewing files that changed from the base of the PR and between fa04311 and 47e5c2a.

📒 Files selected for processing (1)

• packages/cli/src/screens/dev-screen.tsx

---

📝 Walkthrough

Walkthrough

This PR updates the CLI dev UI and watcher, and enhances the core sync engine and metadata handling. It replaces the ASCII banner with a styled Banner component, ensures quit hotkey fully exits the dev process, converts the watcher to a callback-driven API with conditional restart logic, implements incremental sync (mtime/frontmatter/hash checks, concurrent copy, OpenAPI mtime caching), adds writeMetaFiles to pre-create directories and emit _meta.json/_nav.json, and includes small documentation and tooling adjustments.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the primary change: an incremental sync engine optimization for core and CLI packages, which is the main focus of the pull request.
Description check	✅ Passed	The description clearly relates to the changeset, covering the major updates (incremental sync engine, CLI build migration, dev TUI fixes, and sidebar directory creation) and providing a concrete test plan.
Docstring Coverage	✅ Passed	Docstring coverage is 96.67% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 10

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/cli/src/lib/watcher.ts (1)

139-143: 🧹 Nitpick | 🔵 Trivial

Awkward reduce pattern used to avoid expression statements.

The reduce returning null is a workaround to satisfy the "no expression statements" rule. While technically compliant, this pattern is harder to read than a simple loop or forEach. Consider using a more idiomatic approach if the linting rules allow.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/cli/src/lib/watcher.ts` around lines 139 - 143, The callback passed
to watch (used to create the watcher constant) uses an awkward
Array.prototype.reduce returning null to avoid expression statements; replace
that reduce with a clearer imperative loop (e.g., forEach or for...of) inside
the (_event, filename) => { ... } handler so you can perform side-effecting
operations directly and remove the null return workaround, leaving the watcher,
watch, and repoRoot usages intact.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@contributing/concepts/engine/incremental.md`:
- Line 81: Replace the British English "afterwards" with American English
"afterward" in the sentence "Empty parent directories are pruned afterwards."
within the incremental.md content so the line reads "Empty parent directories
are pruned afterward." to maintain consistent American spelling.

In `@contributing/concepts/engine/openapi.md`:
- Line 62: Replace the double hyphen in the link text "Dev Mode -- OpenAPI
Cache" with an em dash for typographic consistency; update the markdown so the
link reads "Dev Mode — OpenAPI Cache" (keep the URL ./dev.md#openapi-cache and
surrounding sentence unchanged) to improve readability.

In `@contributing/concepts/engine/overview.md`:
- Around line 27-30: Update the OpenAPI input node label to reflect that specs
are sourced from configuration rather than a fixed filename: change the SPECS
node's label (currently "openapi.yaml") to something like "config.openapi.spec"
or "OpenAPI spec files (from zpress.config.ts)" and mention/respect the single
source of truth symbol CONFIG (zpress.config.ts) and the runtime boundary
loadConfig(); ensure any text or diagram note references that specs come from
the zpress.config.ts/workspace openapi config and that outputs assume the
.zpress/content/ root and .zpress/content/.generated/ for generated metadata.

In `@packages/cli/kidd.config.ts`:
- Around line 3-6: Summary: enable TypeScript declaration emission by adding
dts: true to the Kidd config. Fix: update the exported config object passed to
defineConfig in kidd.config.ts to include dts: true alongside the existing
commands and entry keys (e.g., export default defineConfig({ commands:
'./src/commands', entry: './src/index.ts', dts: true })), so tsdown will emit
./dist/index.d.ts that matches the package's exports.types entry.

In `@packages/cli/src/lib/watcher.ts`:
- Around line 230-243: The current restartRelevantHash function uses
JSON.stringify on the relevant object which can produce nondeterministic key
ordering and cause spurious hash changes; update restartRelevantHash to produce
a deterministic serialization (e.g., implement a stable stringify that sorts
object keys recursively or use a canonicalization helper) before passing to
createHash('sha256').update(...).digest('hex'), and apply it to the constructed
relevant object (fields: title, description, tagline, icon, theme, sidebar,
socialLinks, footer, home, openapi) so identical content with different
insertion orders yields the same hash.

In `@packages/cli/src/stories/dev.stories.tsx`:
- Around line 43-45: DevScreenPreview accepts an unbounded width so code that
computes width - 2 can produce negative values; guard and normalize the prop at
the top of DevScreenPreview by deriving a safeWidth (e.g., clamp to a minimum of
2 or coerce to a number with a sensible default) and then use safeWidth
everywhere instead of width (this will prevent negative widths passed to Alert
and separators referenced in the function and other places that compute width -
2).

In `@packages/config/schemas/schema.json`:
- Line 3: Regenerate the published schema.json (update the $id) after modifying
the schema so that title under ZpressConfig →
properties.apps.items.properties.title and the analogous locations for packages
and workspaces[].items accept only a plain string (remove or stop referencing
the TitleConfig object-form there); ensure TitleConfig remains reserved for
Section node shapes only and update any $ref entries so those three paths point
to a simple string schema (not the object TitleConfig), then rebuild/export the
schema.json so the new $id matches the regenerated file.

In `@packages/core/src/banner/index.ts`:
- Around line 164-173: Read the file contents into existing as you already do,
but normalize CRLF to LF before doing the marker and equality checks: convert
existing (and newContent for the equality check) to a normalized form (e.g.,
replace "\r\n" with "\n") and then derive firstLine from the normalized string;
then compare firstLine to GENERATED_MARKER and compare the normalized existing
to the normalized newContent. Update the logic around existing, firstLine,
GENERATED_MARKER and newContent to use the normalized strings so Windows CRLF
doesn't break the checks.

In `@packages/core/src/sync/copy.ts`:
- Around line 29-32: The fast-path after calling tryMtimeSkip(page, ctx) should
not return the cached result unless the materialized file actually exists on
disk; update the logic so that after obtaining a non-null cached value you
verify the corresponding materialized file (e.g., the .zpress/content entry or
the page's output path resolved from ctx/page) exists and is readable, and only
then return cached—otherwise proceed with rewrite. Apply the same existence
check to the other fast-path in the same module (the block referenced at lines
~131-163) so both shortcuts validate on-disk presence before skipping
regeneration.

In `@packages/core/src/sync/openapi.ts`:
- Around line 60-64: The reducer for specMtimes mutates the accumulator via
Object.assign(acc, result.specMtimes); change reduce on configResults to collect
entries immutably (e.g., accumulate arrays of [key,value] or use a new object
returned each iteration) and only materialize the final Record<string, number>
once so specMtimes is created without mutating prior state; update the reduce
usage around specMtimes/configResults to return a new object or gather entries
and then build the final specMtimes map after reduction.

---

Outside diff comments:
In `@packages/cli/src/lib/watcher.ts`:
- Around line 139-143: The callback passed to watch (used to create the watcher
constant) uses an awkward Array.prototype.reduce returning null to avoid
expression statements; replace that reduce with a clearer imperative loop (e.g.,
forEach or for...of) inside the (_event, filename) => { ... } handler so you can
perform side-effecting operations directly and remove the null return
workaround, leaving the watcher, watch, and repoRoot usages intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a98b7d92-0963-4ae8-aedb-4bbaac88a941

📥 Commits

Reviewing files that changed from the base of the PR and between 61b7b7d and a7a8647.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml, !pnpm-lock.yaml

📒 Files selected for processing (52)

• .changeset/fix-dev-banner-and-exit.md
• .changeset/fix-meta-missing-dirs.md
• .changeset/incremental-sync-engine.md
• CONTRIBUTING.md
• contributing/README.md
• contributing/concepts/architecture.md
• contributing/concepts/cli.md
• contributing/concepts/config.md
• contributing/concepts/engine/dev.md
• contributing/concepts/engine/incremental.md
• contributing/concepts/engine/openapi.md
• contributing/concepts/engine/overview.md
• contributing/concepts/engine/pipeline.md
• contributing/guides/getting-started.md
• contributing/references/cli.md
• package.json
• packages/cli/kidd.config.ts
• packages/cli/package.json
• packages/cli/rslib.config.ts
• packages/cli/src/commands/build.ts
• packages/cli/src/commands/check.ts
• packages/cli/src/commands/clean.ts
• packages/cli/src/commands/dev.ts
• packages/cli/src/commands/diff.ts
• packages/cli/src/commands/draft.ts
• packages/cli/src/commands/dump.ts
• packages/cli/src/commands/serve.ts
• packages/cli/src/commands/setup.ts
• packages/cli/src/index.ts
• packages/cli/src/lib/dev-types.ts
• packages/cli/src/lib/rspress.ts
• packages/cli/src/lib/watcher.ts
• packages/cli/src/screens/dev-screen.tsx
• packages/cli/src/stories/dev.stories.tsx
• packages/cli/tsconfig.json
• packages/config/schemas/schema.json
• packages/core/src/banner/index.ts
• packages/core/src/sync/copy.ts
• packages/core/src/sync/images.ts
• packages/core/src/sync/index.ts
• packages/core/src/sync/openapi.ts
• packages/core/src/sync/sidebar/index.ts
• packages/core/src/sync/sidebar/meta.ts
• packages/core/src/sync/sidebar/multi.test.ts
• packages/core/src/sync/sidebar/multi.ts
• packages/core/src/sync/sidebar/write-meta.ts
• packages/core/src/sync/types.ts
• packages/ui/src/config.ts
• packages/ui/src/theme/components/sidebar/sidebar-scope.tsx
• packages/ui/src/theme/hooks/use-zpress.ts
• packages/ui/src/theme/index.tsx
• zpress.config.ts

💤 Files with no reviewable changes (4)

• packages/cli/rslib.config.ts
• contributing/concepts/cli.md
• packages/core/src/sync/sidebar/multi.test.ts
• packages/core/src/sync/sidebar/multi.ts

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

packages/cli/src/lib/watcher.ts (2)

48-58: 🛠️ Refactor suggestion | 🟠 Major

Avoid adding more let-backed watcher state.

The new sync coordinator suppresses the repo’s functional TS rule in five places. Please collapse this into an immutable state transition/helper instead of growing a mutable closure; the current reentrancy path is already hard to audit.

As per coding guidelines "No let — only const. No reassignment, no mutation."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/cli/src/lib/watcher.ts` around lines 48 - 58, Replace the multiple
let-backed pieces of watcher state (config, syncing, pendingReloadConfig,
consecutiveFailures) with a single immutable watcher state and a pure
reducer/updater function (e.g., transitionWatcherState or watchStateReducer)
that returns new state objects instead of mutating variables; keep
callbacks.onStatusChange usage but call it with the new state's status. Locate
uses of config, syncing, pendingReloadConfig, and consecutiveFailures and adapt
them to read from the single state object and dispatch actions (e.g., { type:
'startSync'|'finishSync'|'fail'|'reloadConfig' }) to the reducer which returns
the updated state, ensuring no let or in-place mutation remains in the closure.

---

125-133: ⚠️ Potential issue | 🟠 Major

Don't drop non-markdown sync inputs.

After the root zpress.config.* special case, every other change is ignored unless the path ends in .md/.mdx. That skips imported config helpers, OpenAPI specs, public assets, and other non-markdown sync inputs, so dev can keep serving stale output until a manual resync or an unrelated markdown save.

Also applies to: 152-163

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli/src/screens/dev-screen.tsx`:
- Around line 242-243: Clamp the computed terminal width to a safe minimum
before using it: replace the direct const width = Math.min(columns, 80) with a
clamped value (e.g., const width = Math.max(Math.min(columns, 80), 2)) so width
- 2 cannot go negative; then use this clamped width everywhere you derive layout
sizes (the separator render and the error alert code paths that currently rely
on width/columns) to avoid unstable rendering. Make sure any other calculations
in the same file that read columns or recompute sizes (the blocks around the
current width usage) use this clamped variable rather than raw columns.
- Around line 225-239: The input handler in useInput (dev-screen.tsx) returns
early when phase !== 'ready', which prevents the quit keys from working during
loading/error; change the handler so it first checks for quit keys (input ===
'q' or key.ctrl && input === 'c') and performs the watcherRef.current.close(),
exit(), and process.exit(0) path regardless of phase, and only after that apply
the phase !== 'ready' early-return for other keys/behavior; keep references to
watcherRef.current, exit(), and process.exit as used now and do not alter
isActive logic.
- Around line 143-145: The TUI currently only stores and renders the watcher
status enum (collapsing errors to "● Error") instead of the full WatcherStatus
with its message; update the watcher state to store the entire WatcherStatus
object (including message) and change the callbacks to pass the full status
object—specifically modify the WatcherCallbacks usage in the callbacks object
(onStatusChange: guard(setWatcherStatus) and onSyncComplete) so they call
setWatcherStatus with the whole WatcherStatus, and update the render/path that
shows the tag (the component that reads watcher status) to display
status.message when status.type === 'error' (or otherwise show the message)
rather than only the status label. Ensure types (WatcherStatus/WatcherCallbacks)
align with this change.

---

Outside diff comments:
In `@packages/cli/src/lib/watcher.ts`:
- Around line 48-58: Replace the multiple let-backed pieces of watcher state
(config, syncing, pendingReloadConfig, consecutiveFailures) with a single
immutable watcher state and a pure reducer/updater function (e.g.,
transitionWatcherState or watchStateReducer) that returns new state objects
instead of mutating variables; keep callbacks.onStatusChange usage but call it
with the new state's status. Locate uses of config, syncing,
pendingReloadConfig, and consecutiveFailures and adapt them to read from the
single state object and dispatch actions (e.g., { type:
'startSync'|'finishSync'|'fail'|'reloadConfig' }) to the reducer which returns
the updated state, ensuring no let or in-place mutation remains in the closure.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: aaefb94b-f73e-4a65-8456-953f33d0f156

📥 Commits

Reviewing files that changed from the base of the PR and between a7a8647 and 5435d8c.

📒 Files selected for processing (6)

• .changeset/fix-home-page-hmr.md
• packages/cli/src/components/banner.tsx
• packages/cli/src/lib/watcher.ts
• packages/cli/src/screens/dev-screen.tsx
• packages/cli/src/stories/banner.stories.tsx
• packages/cli/src/stories/dev.stories.tsx

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/cli/src/screens/dev-screen.tsx`:
- Around line 280-283: The inline ternary in the watcher error label should be
removed; compute the label before JSX or use a match expression instead of `?:`.
For example, derive a string like `const watcherErrorLabel = watcherStatus._tag
=== 'error' ? \`: ${watcherStatus.message}\` : ''` using an if/else or
ts-pattern `match` (reference symbols: watcherStatus and the Text rendering
block that uses `.with('error', () => (`)) and then render `<Text color="red">●
Error{watcherErrorLabel}</Text>` so no ternary remains inside the JSX
expression.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 364b3c32-cef0-4eb5-83c8-ee83cc26e1e9

📥 Commits

Reviewing files that changed from the base of the PR and between 5435d8c and fa04311.

📒 Files selected for processing (8)

• contributing/concepts/engine/incremental.md
• contributing/concepts/engine/openapi.md
• contributing/concepts/engine/overview.md
• packages/cli/package.json
• packages/cli/src/screens/dev-screen.tsx
• packages/cli/src/stories/dev.stories.tsx
• packages/core/src/banner/index.ts
• packages/core/src/sync/copy.ts