diff --git a/.claude/commands/release-snapshot.md b/.claude/commands/release-snapshot.md new file mode 100644 index 00000000..2bb65c51 --- /dev/null +++ b/.claude/commands/release-snapshot.md @@ -0,0 +1,91 @@ +# 发布 Libro 测试版本 + +发布 libro 的测试版本（snapshot release）。 + +## 执行步骤 + +请按顺序执行以下命令： + +1. **生成 changeset 文件**（需要用户在终端中交互操作） + + ```bash + pnpm run changeset + ``` + + 这会启动交互式界面，让用户选择: + - 要发布的包（按空格选择，回车确认） + - 版本变更类型（major/minor/patch） + - 变更说明 + + **注意**：此步骤需要用户手动在终端中完成交互。 + +2. **构建项目** + + ```bash + pnpm run build + ``` + + 构建所有包，确保代码可以正常编译。 + +3. **发布 snapshot 版本** + + ```bash + sh ./scripts/release-snapshot.sh + ``` + + 此脚本会执行： + - `changeset version --snapshot` - 更新版本号 + - `changeset publish --tag snapshot` - 发布到 npm 的 snapshot tag + +4. **生成 resolutions 配置** + + 发布成功后，执行以下命令获取最新 snapshot 版本号： + + ```bash + npm view @difizen/libro-core versions --json | jq -r '.[] | select(contains("snapshot"))' | tail -1 + ``` + + 使用获取到的版本号（如 `0.0.0-snapshot-20260203035545`），生成如下格式的 resolutions： + + ```json + "resolutions": { + "@difizen/libro-ai-native": "", + "@difizen/libro-app": "", + "@difizen/libro-code-cell": "", + "@difizen/libro-code-editor": "", + "@difizen/libro-codemirror": "", + "@difizen/libro-cofine-editor": "", + "@difizen/libro-cofine-editor-contribution": "", + "@difizen/libro-cofine-editor-core": "", + "@difizen/libro-cofine-textmate": "", + "@difizen/libro-common": "", + "@difizen/libro-core": "", + "@difizen/libro-jupyter": "", + "@difizen/libro-kernel": "", + "@difizen/libro-l10n": "", + "@difizen/libro-lab": "", + "@difizen/libro-language-client": "", + "@difizen/libro-lsp": "", + "@difizen/libro-markdown": "", + "@difizen/libro-markdown-cell": "", + "@difizen/libro-output": "", + "@difizen/libro-prompt-cell": "", + "@difizen/libro-raw-cell": "", + "@difizen/libro-rendermime": "", + "@difizen/libro-search": "", + "@difizen/libro-search-code-cell": "", + "@difizen/libro-shared-model": "", + "@difizen/libro-sql-cell": "", + "@difizen/libro-terminal": "", + "@difizen/libro-toc": "", + "@difizen/libro-virtualized": "", + "@difizen/libro-widget": "" + } + ``` + +## 注意事项 + +- 确保在执行前工作目录是干净的（没有未提交的更改会影响发布） +- `pnpm run changeset` 需要用户在终端中交互操作，无法自动完成 +- 如果构建失败，不要执行发布脚本 +- 发布成功后，告知用户发布的版本号并提供完整的 resolutions 配置 diff --git a/.claude/commands/release.md b/.claude/commands/release.md new file mode 100644 index 00000000..358b7dc1 --- /dev/null +++ b/.claude/commands/release.md @@ -0,0 +1,55 @@ +# 发布 Libro 正式版本 + +发布 libro 的正式版本（formal release）。 + +## 执行步骤 + +请按顺序执行以下步骤： + +1. **生成 changeset 文件**（需要用户在终端中交互操作） + + ```bash + pnpm run changeset + ``` + + 这会启动交互式界面，让用户选择: + - 要发布的包（按空格选择，回车确认） + - 版本变更类型（major/minor/patch） + - 变更说明 + + **注意**：此步骤需要用户手动在终端中完成交互。 + +2. **构建项目** + + ```bash + pnpm run build + ``` + + 构建所有包，确保代码可以正常编译。 + +3. **更新版本号** + + ```bash + pnpm changeset version + ``` + + 此命令会根据 changeset 文件更新所有包的版本号，并生成/更新 CHANGELOG.md 文件。 + +4. **发布到 npm** + + ```bash + pnpm changeset publish + ``` + + 发布所有包到 npm（默认使用 `latest` tag）。 + +5. **输出发布结果** + + 发布成功后，告知用户发布的版本号。 + +## 注意事项 + +- 确保在执行前工作目录是干净的（没有未提交的更改会影响发布） +- 如果构建失败，不要继续执行后续步骤 +- 正式版本发布后，需要将 changeset 文件和版本更新提交到 git +- 发布成功后，通常需要创建 git tag 并推送到远程仓库 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..847fa9c7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,119 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Libro is a JavaScript + Python hybrid monorepo providing a Notebook product solution with AI capabilities. It supports kernel-level extensibility and defines workflows for large models. + +## Development Commands + +```bash +# Initial setup (installs dependencies and builds packages) +pnpm bootstrap + +# Start development server (docs/demo site) +pnpm run docs + +# Build all packages +pnpm run build + +# Lint code +pnpm run lint + +# Run all tests +pnpm run test + +# Run tests for a specific package +pnpm run test:jest --filter=@difizen/libro-core + +# Type check +pnpm run tsc + +# Create changeset for version management +pnpm run changeset + +# Run CI checks (lint, typecheck, coverage) +pnpm run ci:check +``` + +## Architecture + +### Dependency Injection Framework + +Libro uses `@difizen/mana-app` for dependency injection. Core patterns: + +- **ManaModule**: Modules are created using `ManaModule.create().register(...).dependOn(...)` +- **@singleton / @transient**: Class decorators for DI scope +- **@inject**: Property/constructor injection +- **@prop()**: Reactive properties with MobX-like behavior +- **Contributions**: Use `.contribution(Token)` to register providers, then inject `@inject(Token)` to get all contributions + +### Core Package Structure (`@difizen/libro-core`) + +- **LibroModule**: Main module that registers core services and depends on sub-modules +- **LibroService**: Manages notebook views/models, tracks active/focus state, emits events +- **LibroModel**: Notebook model containing cells and metadata +- **LibroView**: Notebook view component +- **LibroCellModule**: Cell system with `CellViewContribution` and `CellModelContribution` for registering cell types + +### Cell System + +Cells follow a contribution pattern. To add a new cell type: + +1. Create `CellViewContribution` - provides the view component +2. Create `CellModelContribution` - provides factory for the model +3. Register both in your module + +Existing cell types: `code-cell`, `markdown-cell`, `prompt-cell`, `sql-cell`, `raw-cell` + +### Kernel Architecture (`@difizen/libro-kernel`) + +- **IKernelConnection**: Interface for kernel communication +- **ExecutableNotebookModel**: Extends NotebookModel with kernel connection support +- Kernel connection is managed per notebook instance + +### Key Packages + +| Package | Purpose | +| ----------------------- | ------------------------------------------------------ | +| `libro-core` | Core notebook functionality, model/view, cell system | +| `libro-kernel` | Kernel connection management | +| `libro-jupyter` | Jupyter protocol implementation, integrates cell types | +| `libro-lab` | Full lab application combining all features | +| `libro-ai-native` | AI capabilities (completion, chat, error fixing) | +| `libro-codemirror` | CodeMirror editor integration | +| `libro-cofine-editor-*` | Advanced editor features (LSP, textmate) | +| `libro-rendermime` | MIME type rendering for outputs | +| `libro-output` | Output display components | + +### Build System + +- **pnpm** with workspaces for monorepo management +- **nx** for task orchestration with caching +- **father** for building individual packages (ESM output to `es/`) + +### Version Management + +- Uses **changesets** for version management +- All `@difizen/*` packages are linked together (same version) +- Run `pnpm run changeset` to create version changes + +## Release Process + +1. Create changeset: `pnpm run changeset` (or auto-generate for snapshots) +2. Build: `pnpm run build` +3. For snapshot release: `sh ./scripts/release-snapshot.sh` + +## Commit Convention + +Follow Angular commit guidelines: + +- `feat(scope): description` - new feature +- `fix(scope): description` - bug fix +- `chore(scope): description` - maintenance + +## Requirements + +- Node.js 20.x +- pnpm 8.15.6