@openwebf/webf 0.1.0

package/CLAUDE.md

@@ -0,0 +1,206 @@
+# WebF CLI Development Guide
+
+## Overview
+The WebF CLI is a code generation tool that creates type-safe bindings between Flutter/Dart and JavaScript frameworks (React, Vue). It analyzes TypeScript definition files and generates corresponding Dart classes and JavaScript/TypeScript components.
+
+## Architecture
+
+### Core Components
+- `analyzer.ts` - TypeScript AST analysis with multi-level caching
+- `generator.ts` - Orchestrates code generation for Dart, React, and Vue
+- `dart.ts` - Dart code generation from TypeScript definitions
+- `react.ts` - React component generation
+- `vue.ts` - Vue component generation
+- `commands.ts` - CLI command implementations
+- `logger.ts` - Logging utility without external dependencies
+
+### Key Features
+- Multi-level caching for performance optimization
+- Parallel file processing
+- Type-safe attribute handling with automatic conversions
+- Comprehensive error handling and recovery
+
+## Code Generation Patterns
+
+### TypeScript to Dart Type Mapping
+```typescript
+// Boolean attributes are always non-nullable in Dart
+interface Props {
+  open?: boolean;  // Generates: bool get open;
+  title?: string;  // Generates: String? get title;
+}
+```
+
+### Attribute Type Conversion
+HTML attributes are always strings, so the generator includes automatic type conversion:
+- Boolean: `value == 'true' || value == ''`
+- Integer: `int.tryParse(value) ?? 0`
+- Double: `double.tryParse(value) ?? 0.0`
+- String: Direct assignment
+
+## Performance Optimizations
+
+### Caching Strategy
+1. **Source File Cache**: Parsed TypeScript AST files are cached
+2. **Type Conversion Cache**: Frequently used type conversions are cached
+3. **File Content Cache**: File contents are cached to detect changes
+
+### Batch Processing
+Files are processed in batches for optimal parallelism:
+```typescript
+await processFilesInBatch(items, batchSize, processor);
+```
+
+## Testing Guidelines
+
+### Test Structure
+- Unit tests for all core modules
+- Mock file system operations before module imports
+- Test coverage threshold: 70%
+
+### Running Tests
+```bash
+npm test                    # Run all tests
+npm test -- test/analyzer.test.ts  # Run specific test
+npm run test:coverage       # Run with coverage report
+```
+
+### Mock Patterns
+For modules that read files at load time:
+```typescript
+jest.mock('fs');
+import fs from 'fs';
+const mockFs = fs as jest.Mocked<typeof fs>;
+mockFs.readFileSync = jest.fn().mockImplementation((path) => {
+  // Return appropriate content
+});
+// Now import the module
+import { moduleUnderTest } from './module';
+```
+
+## CLI Usage
+
+### Commands
+```bash
+# Generate code from TypeScript definitions (auto-creates project if needed)
+webf codegen <output-dir> --flutter-package-src=<path> [--framework=react|vue] [--package-name=<name>] [--publish-to-npm] [--npm-registry=<url>]
+
+# Create a new project without code generation
+webf codegen <output-dir> [--framework=react|vue] [--package-name=<name>]
+
+# Generate and publish to npm
+webf codegen <output-dir> --flutter-package-src=<path> --publish-to-npm
+
+# Generate and publish to custom registry
+webf codegen <output-dir> --flutter-package-src=<path> --publish-to-npm --npm-registry=https://custom.registry.com/
+```
+
+### Auto-creation Behavior
+The `generate` command now automatically detects if a project needs to be created:
+- If required files (package.json, global.d.ts, tsconfig.json) are missing, it will create a new project
+- If framework or package name are not provided, it will prompt interactively
+- If an existing project is detected, it will use the existing configuration
+- Framework can be auto-detected from existing package.json dependencies
+
+### Metadata Synchronization
+When creating typing projects, the CLI automatically synchronizes metadata from the Flutter package:
+- Reads `pubspec.yaml` from the Flutter package source directory
+- Extracts version and description information
+- Applies this metadata to the generated `package.json` files
+- Ensures typing packages match the same version as the Flutter package
+
+### Automatic Build
+After code generation, the CLI automatically runs `npm run build` if a build script is present in the package.json. This ensures the generated package is immediately ready for use or publishing. The build process:
+- Checks for the presence of a `build` script in package.json
+- Runs the build command if available
+- Continues successfully even if the build fails (with a warning)
+- Provides clear console output about the build status
+
+### NPM Publishing
+The CLI supports automatic npm publishing with the following features:
+- **--publish-to-npm**: Automatically publishes the generated package to npm (build is run automatically)
+- **--npm-registry**: Specify a custom npm registry URL (defaults to https://registry.npmjs.org/)
+- **Interactive publishing**: If not using the --publish-to-npm flag, the CLI will ask if you want to publish after generation
+- **Registry configuration**: When choosing to publish interactively, you can specify a custom registry URL
+- Checks if user is logged in before attempting to publish
+- Temporarily sets and resets registry configuration when custom registry is used
+
+Requirements for publishing:
+- Must be logged in to npm (`npm login`)
+- Package must have a valid package.json
+- Package will be built automatically before publishing (if build script exists)
+
+Publishing workflow:
+1. If `--publish-to-npm` is not specified, CLI prompts after successful generation
+2. If user chooses to publish, CLI asks for registry URL (optional)
+3. Validates npm login status
+4. Publishes to specified registry (no need to build separately)
+
+### Output Directory Behavior
+- Dart files are generated in the Flutter package source directory
+- React/Vue files are generated in the specified output directory
+- If no output directory is specified, a temporary directory is created
+- Temporary directories are created in the system temp folder with prefix `webf-typings-`
+- When using temporary directories, the path is displayed at the end of generation
+- Paths can be absolute or relative to current working directory
+
+### Generated Files Structure
+When running `dartGen`:
+- Dart binding files are generated with `_bindings_generated.dart` suffix
+- Original `.d.ts` files are copied to the output directory maintaining their structure
+- An `index.d.ts` file is generated with:
+  - TypeScript triple-slash references to all `.d.ts` files
+  - ES module exports for all type definitions
+  - Package metadata from `pubspec.yaml` in documentation comments
+- Directory structure from source is preserved in the output
+
+## Development Workflow
+
+### Adding New Features
+1. Update TypeScript interfaces/types
+2. Implement feature with tests
+3. Update templates if needed
+4. Ensure all tests pass
+5. Update this documentation
+
+### Debugging
+Use the logger for debugging:
+```typescript
+import { debug, info, warn, error } from './logger';
+debug('Processing file:', filename);
+```
+
+### Template Modification
+Templates are in `/templates/*.tpl`. When modifying:
+1. Update the template file
+2. Update the corresponding generator function
+3. Ensure generated code follows style guidelines
+
+## Common Issues and Solutions
+
+### Issue: Boolean attributes treated as strings
+**Solution**: Use `generateAttributeSetter` which handles type conversion
+
+### Issue: Null type handling
+**Solution**: Check for literal types containing null:
+```typescript
+if (type.kind === ts.SyntaxKind.LiteralType) {
+  const literalType = type as ts.LiteralTypeNode;
+  if (literalType.literal.kind === ts.SyntaxKind.NullKeyword) {
+    return FunctionArgumentType.null;
+  }
+}
+```
+
+### Issue: File changes not detected
+**Solution**: Clear caches before generation:
+```typescript
+clearCaches();
+```
+
+## Code Style
+- Use async/await for asynchronous operations
+- Implement proper error handling with try-catch
+- Add descriptive error messages
+- Use TypeScript strict mode
+- Follow existing patterns in the codebase

package/README-zhCN.md

@@ -0,0 +1,256 @@
+# WebF CLI
+
+一个用于生成 Flutter 类和 Vue/React 组件声明文件的命令行工具。
+
+## 安装
+
+```bash
+npm install -g @openwebf/webf
+```
+
+## 使用方法
+
+WebF CLI 提供三个主要命令：
+
+### 1. 初始化类型定义
+
+在项目中初始化 WebF 类型定义：
+
+```bash
+webf init <目标目录>
+```
+
+这将在指定目录中创建必要的类型定义文件。
+
+### 2. 创建新项目
+
+创建一个新的 Vue 或 React 项目：
+
+```bash
+webf create <目标目录> --framework <框架> --package-name <包名>
+```
+
+选项：
+- `--framework`：选择 'vue' 或 'react'
+- `--package-name`：指定包名
+
+示例：
+```bash
+webf create my-webf-app --framework react --package-name @myorg/my-webf-app
+```
+
+### 3. 生成代码
+
+生成 Flutter 类和组件声明文件：
+
+```bash
+webf generate <目标路径> --flutter-package-src <Flutter源码路径> --framework <框架>
+```
+
+选项：
+- `--flutter-package-src`：Flutter 包源码路径
+- `--framework`：选择 'vue' 或 'react'
+
+示例：
+```bash
+webf generate ./src --flutter-package-src ./flutter_package --framework react
+```
+
+## 实现细节
+
+### 类型系统
+
+CLI 使用复杂的类型系统来处理各种数据类型：
+
+- 基本类型：
+  - `string`（DOM 字符串）
+  - `number`（整数/浮点数）
+  - `boolean`（布尔值）
+  - `any`（任意类型）
+  - `void`（空类型）
+  - `null`（空值）
+  - `undefined`（未定义）
+
+- 复杂类型：
+  - 数组：`Type[]`
+  - 函数：`Function`
+  - Promise：`Promise<Type>`
+  - 自定义事件：`CustomEvent`
+  - 布局依赖类型：`DependentsOnLayout<Type>`
+
+### 命名约定和文件结构
+
+#### 接口命名模式
+
+CLI 遵循特定的接口命名模式：
+
+1. **组件接口**：
+   - 属性接口：`{组件名称}Properties`
+   - 事件接口：`{组件名称}Events`
+   - 示例：`ButtonProperties`、`ButtonEvents`
+
+2. **生成的文件名**：
+   - React 组件：`{组件名称}.tsx`
+   - Vue 组件：`{组件名称}.vue`
+   - Flutter 类：`{组件名称}.dart`
+   - 类型定义：`{组件名称}.d.ts`
+
+3. **名称转换**：
+   - 组件名称提取：
+     - 从 `{名称}Properties` → `{名称}`
+     - 从 `{名称}Events` → `{名称}`
+   - 示例：`ButtonProperties` → `Button`
+
+#### 生成的组件名称
+
+1. **React 组件**：
+   - 标签名：`<{组件名称} />`
+   - 文件名：`{组件名称}.tsx`
+   - 示例：`ButtonProperties` → `<Button />` 在 `button.tsx` 中
+
+2. **Vue 组件**：
+   - 标签名：`<{组件名称}-component />`
+   - 文件名：`{组件名称}.vue`
+   - 示例：`ButtonProperties` → `<button-component />` 在 `button.vue` 中
+
+3. **Flutter 类**：
+   - 类名：`{组件名称}`
+   - 文件名：`{组件名称}.dart`
+   - 示例：`ButtonProperties` → `Button` 类在 `button.dart` 中
+
+#### 类型定义文件
+
+1. **文件位置**：
+   - React：`src/components/{组件名称}.d.ts`
+   - Vue：`src/components/{组件名称}.d.ts`
+   - Flutter：`lib/src/{组件名称}.dart`
+
+2. **接口结构**：
+   ```typescript
+   interface {组件名称}Properties {
+     // 属性
+   }
+
+   interface {组件名称}Events {
+     // 事件
+   }
+   ```
+
+3. **组件注册**：
+   - React：在 `index.ts` 中导出
+   - Vue：在组件声明文件中注册
+   - Flutter：在库文件中导出
+
+### 组件生成
+
+#### React 组件
+- 生成带有适当类型定义的 TypeScript React 组件
+- 处理带有正确事件类型的事件绑定
+- 支持带有基于 Promise 返回类型的异步方法
+- 将事件名称转换为 React 约定（如 `onClick`、`onChange`）
+
+#### Vue 组件
+- 生成 Vue 组件类型声明
+- 支持 Vue 的事件系统
+- 使用适当的 TypeScript 类型处理属性和事件
+- 生成组件注册代码
+
+#### Flutter 类
+- 生成带有适当类型映射的 Dart 类
+- 使用正确的参数类型处理方法声明
+- 支持异步操作
+- 生成适当的事件处理器类型
+
+### 类型分析
+
+CLI 使用 TypeScript 的编译器 API 来分析和处理类型定义：
+
+1. 解析 TypeScript 接口声明
+2. 分析类关系和继承
+3. 处理方法签名和参数类型
+4. 处理联合类型和复杂类型表达式
+5. 为每个目标平台生成适当的类型映射
+
+### 代码生成约定
+
+1. **命名约定**：
+   - 属性：camelCase
+   - 事件：带 'on' 前缀的 camelCase
+   - 方法：camelCase
+   - 类：PascalCase
+
+2. **类型映射**：
+   - TypeScript → Dart：
+     - `string` → `String`
+     - `number` → `int`/`double`
+     - `boolean` → `bool`
+     - `any` → `dynamic`
+     - `void` → `void`
+
+   - TypeScript → React/Vue：
+     - `string` → `string`
+     - `number` → `number`
+     - `boolean` → `boolean`
+     - `any` → `any`
+     - `void` → `void`
+
+3. **事件处理**：
+   - React：`EventHandler<SyntheticEvent<Element>>`
+   - Vue：`Event`/`CustomEvent`
+   - Flutter：`EventHandler<Event>`
+
+## 项目结构
+
+运行命令后，您的项目将具有以下结构：
+
+### React 项目
+```
+my-webf-app/
+├── src/
+│   ├── components/
+│   │   ├── button.tsx
+│   │   ├── button.d.ts
+│   │   └── index.ts
+│   ├── utils/
+│   │   └── createComponent.ts
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+### Vue 项目
+```
+my-webf-app/
+├── src/
+│   ├── components/
+│   │   ├── button.vue
+│   │   └── button.d.ts
+├── package.json
+└── tsconfig.json
+```
+
+## 依赖项
+
+CLI 会自动为所选框架安装必要的依赖项：
+- React：React 及相关类型定义
+- Vue：Vue 及相关类型定义
+
+## 开发
+
+### 从源码构建
+
+```bash
+npm install
+npm run build
+```
+
+### 测试
+
+```bash
+npm test
+```
+
+## 许可证
+
+ISC

package/README.md

@@ -0,0 +1,232 @@
+# WebF CLI
+
+A powerful code generation tool for WebF that creates type-safe bindings between Flutter/Dart and JavaScript frameworks (React, Vue). It analyzes TypeScript definition files and generates corresponding Dart classes and JavaScript/TypeScript components.
+
+## Installation
+
+```bash
+npm install -g @openwebf/webf
+```
+
+## Usage
+
+### Generate Code
+
+The `webf codegen` command generates Dart abstract classes and React/Vue components from TypeScript definitions. It automatically creates a project if needed.
+
+```bash
+webf codegen [output-dir] [options]
+```
+
+#### Arguments:
+- `output-dir`: Path to output generated files (default: ".")
+
+#### Options:
+- `--flutter-package-src <path>`: Flutter package source path containing TypeScript definitions
+- `--framework <framework>`: Target framework - 'react' or 'vue'
+- `--package-name <name>`: Package name for the webf typings
+- `--publish-to-npm`: Automatically publish the generated package to npm
+- `--npm-registry <url>`: Custom npm registry URL (defaults to https://registry.npmjs.org/)
+
+#### Examples:
+
+**Generate code with auto-creation of project:**
+```bash
+# Generate React components from Flutter package
+webf codegen my-typings --flutter-package-src=../webf_cupertino_ui --framework=react
+
+# Generate Vue components with custom package name
+webf codegen my-vue-app --flutter-package-src=./flutter_pkg --framework=vue --package-name=@myorg/webf-vue
+
+# Use temporary directory (auto-created)
+webf codegen --flutter-package-src=../webf_cupertino_ui
+```
+
+**Create a new project without code generation:**
+```bash
+# Create React project structure
+webf codegen my-project --framework=react --package-name=my-webf-react
+
+# Create Vue project structure  
+webf codegen my-project --framework=vue --package-name=my-webf-vue
+```
+
+**Generate and publish to npm:**
+```bash
+# Publish to default npm registry
+webf codegen my-typings --flutter-package-src=../webf_ui --publish-to-npm
+
+# Publish to custom registry
+webf codegen my-typings --flutter-package-src=../webf_ui --publish-to-npm --npm-registry=https://custom.registry.com/
+```
+
+### Interactive Mode
+
+If you don't provide all required options, the CLI will prompt you interactively:
+
+```bash
+webf codegen my-app
+# CLI will ask:
+# - Which framework would you like to use? (react/vue)
+# - What is your package name?
+# - Would you like to publish this package to npm?
+```
+
+## Key Features
+
+### 1. Auto-creation
+The CLI automatically detects if a project needs to be created based on the presence of required files (package.json, global.d.ts, tsconfig.json).
+
+### 2. Flutter Package Detection
+When `--flutter-package-src` is not provided, the CLI searches for a Flutter package in the current directory or parent directories by looking for `pubspec.yaml`.
+
+### 3. Metadata Synchronization
+The CLI reads version and description from the Flutter package's `pubspec.yaml` and applies them to the generated `package.json`.
+
+### 4. Automatic Build
+After code generation, the CLI automatically runs `npm run build` if a build script exists in the package.json.
+
+### 5. Framework Detection
+For existing projects, the CLI can auto-detect the framework from package.json dependencies.
+
+### 6. TypeScript Environment Validation
+The CLI validates that the Flutter package has proper TypeScript configuration:
+- Checks for `tsconfig.json`
+- Verifies `.d.ts` files exist
+- Offers to create `tsconfig.json` if missing
+
+## Generated Project Structure
+
+### React Project
+```
+my-webf-app/
+├── src/
+│   ├── components/
+│   │   ├── Button.tsx
+│   │   ├── Input.tsx
+│   │   └── ...
+│   ├── utils/
+│   │   └── createComponent.ts
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── global.d.ts
+└── .gitignore
+```
+
+### Vue Project
+```
+my-webf-app/
+├── src/
+│   ├── components/
+│   │   ├── Button.vue
+│   │   ├── Input.vue
+│   │   └── ...
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+├── global.d.ts
+└── .gitignore
+```
+
+### Flutter Package (Generated Dart Files)
+```
+flutter_package/
+├── lib/
+│   ├── src/
+│   │   ├── button_bindings_generated.dart
+│   │   ├── input_bindings_generated.dart
+│   │   └── ...
+│   └── widgets.dart
+└── pubspec.yaml
+```
+
+## Type System
+
+The CLI handles comprehensive type mapping between TypeScript and Dart:
+
+### Basic Types
+- `string` → `String` (Dart) / `string` (JS)
+- `number` → `int`/`double` (Dart) / `number` (JS)
+- `boolean` → `bool` (Dart) / `boolean` (JS)
+- `any` → `dynamic` (Dart) / `any` (JS)
+- `void` → `void`
+- `null` → `null`
+- `undefined` → handled specially
+
+### Complex Types
+- Arrays: `Type[]` → `List<Type>` (Dart)
+- Functions: Proper signature conversion
+- Promises: `Promise<Type>` → `Future<Type>` (Dart)
+- Union types: Handled with appropriate conversions
+- Custom types: Preserved with proper imports
+
+### Attribute Type Conversion
+HTML attributes are always strings, so the generator includes automatic type conversion:
+- Boolean: `value == 'true' || value == ''`
+- Integer: `int.tryParse(value) ?? 0`
+- Double: `double.tryParse(value) ?? 0.0`
+- String: Direct assignment
+
+## Performance Optimizations
+
+The CLI implements several performance optimizations:
+
+### Multi-level Caching
+1. **Source File Cache**: Parsed TypeScript AST files
+2. **Type Conversion Cache**: Frequently used type conversions
+3. **File Content Cache**: Detect changes efficiently
+
+### Parallel Processing
+Files are processed in batches for optimal performance, maximizing CPU utilization.
+
+## Development
+
+### Prerequisites
+- Node.js >= 14
+- npm or yarn
+
+### Building from Source
+```bash
+git clone https://github.com/openwebf/webf
+cd webf/cli
+npm install
+npm run build
+```
+
+### Running Tests
+```bash
+npm test                    # Run all tests
+npm test -- --coverage      # Run with coverage
+npm test -- analyzer.test   # Run specific test file
+```
+
+### Development Workflow
+```bash
+# Make changes to source files
+npm run build    # Compile TypeScript
+npm test         # Run tests
+npm link         # Link for local testing
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Missing TypeScript definitions:**
+- Ensure your Flutter package has `.d.ts` files in the `lib/` directory
+- Create a `tsconfig.json` in your Flutter package root
+
+**Build failures:**
+- Check that all dependencies are installed: `npm install`
+- Verify TypeScript compilation: `npm run build`
+
+**Publishing errors:**
+- Ensure you're logged in to npm: `npm login`
+- Verify package name availability
+- Check registry URL if using custom registry
+
+## License
+
+ISC