fix(cli): add "@zenstackhq/schema" package installation for "zenstack create" and "zen init"

[ymc9]

Summary by CodeRabbit

• New Features

  • Schema package is now automatically installed during initial project setup, streamlining the initialization experience.

• Documentation

  • Updated contribution guidelines with explicit guidance on targeting the dev branch for pull requests.

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: Add @zenstackhq/schema package installation

Reviewing the changes to add "@zenstackhq/schema" package installation for CLI commands.

Review Tasks

• Read and analyze changed files
• Review code quality and best practices
• Check for potential bugs or issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage implications
• Provide comprehensive feedback

📋 Summary

This PR adds @zenstackhq/schema@latest as a runtime dependency (not dev dependency) to both the zenstack init command and create-zenstack scaffolding tool. It also adds package.json export for the schema package and updates CLAUDE.md with PR targeting guidelines.

✅ Positive Aspects

1. Consistent Package Management

• Both CLI commands (init and create-zenstack) now consistently install the schema package
• Proper use of package manager detection and command resolution
• Correct installation as runtime dependency (dev: false)

2. Code Quality

• Changes follow existing code patterns and conventions
• Clean integration into existing package installation loops
• Maintains existing error handling patterns

3. Architecture Alignment

• The schema package provides runtime utilities for generated TypeScript schemas (SchemaAccessor, expression utils)
• Installing it during project initialization makes sense for users who need to access schema metadata at runtime

⚠️ Areas for Consideration

1. Missing Documentation (/home/runner/work/zenstack/zenstack/packages/cli/src/actions/init.ts:16, /home/runner/work/zenstack/zenstack/packages/create-zenstack/src/index.ts:70)

• No indication of why the schema package is needed
• Users may be confused about what this package does vs @zenstackhq/orm

2. Test Coverage Gap

• The existing CLI init test is skipped (describe.skip) due to CI timeout issues
• No verification that the schema package is actually installed correctly
• Missing integration test for create-zenstack

3. Version Consistency

• Using @latest tag instead of workspace version references
• Could lead to version mismatches in development

🐛 Potential Issues

Minor: Package.json Export Addition
The schema package.json export addition seems unrelated to the main change:

"./package.json": {
    "import": "./package.json",
    "require": "./package.json"
}

This should probably be in a separate commit/PR for clarity.

🔒 Security & Performance

Security: ✅ No security concerns - installing legitimate ZenStack packages
Performance: ✅ Minimal impact - just adds one more package to installation list

📝 Recommendations

1. Add comments explaining the schema package purpose in both CLI files
2. Consider using workspace versions instead of @latest for consistency
3. Enable and fix the CLI init test to verify schema package installation
4. Separate the package.json export change into its own commit for clarity

🎯 Overall Assessment

This is a solid, low-risk change that correctly adds a missing dependency to CLI initialization commands. The implementation follows existing patterns and doesn't introduce bugs. The main concern is around test coverage and documentation clarity.

Recommendation: ✅ Approve with minor improvements suggested above

---

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7e908f2 and d885279.

📒 Files selected for processing (4)

• CLAUDE.md
• packages/cli/src/actions/init.ts
• packages/create-zenstack/src/index.ts
• packages/schema/package.json

---

📝 Walkthrough

Walkthrough

The changes introduce @zenstackhq/schema as a non-dev dependency to the CLI and create-zenstack initialization processes, add a package.json export entry to the schema package configuration, and append Pull Request guidelines to CLAUDE.md recommending the dev branch as the target.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md	Added Pull Requests section with guidance to target dev branch (not main) when creating PRs.
Installation Dependencies packages/cli/src/actions/init.ts, packages/create-zenstack/src/index.ts	Added @zenstackhq/schema@latest as a non-dev dependency to the initialization flow in both CLI and create-zenstack processes.
Package Configuration packages/schema/package.json	Added new export entry for "./package.json" with import and require mappings in the exports map.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A schema hops into the flow,
New exports dance, dependencies grow,
Dev branch whispers through CLAUDE's call—
Configuration blooms, best of all! 🌱

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding @zenstackhq/schema package installation to both zenstack create and zen init commands.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/schema-package

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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