---
alwaysApply: true
---
# Development Workflow & Scripts
**TypeScript is the primary development language** - All source code is written in TypeScript and compiled to JavaScript.
## Available Scripts
### Build & Development
- `npm run build` - Clean and compile TypeScript to `dist/`
- `npm run clean` - Remove `dist/` and `temp_images/` directories
- `npm run dev:cli` - Run CLI in development mode with tsx
- `npm run dev:mcp:stdio` - Run MCP server in stdio mode (development)
- `npm run dev:mcp:http` - Run MCP server in HTTP mode (development)
### Code Quality
- `npm run lint` - Run ESLint on TypeScript files
- `npm run lint:fix` - Fix ESLint issues automatically
- `npm run format` - Format code with Prettier
- `npm run format:check` - Check code formatting
### CLI Commands
- `npm run start:cli` - Run compiled CLI with help
- `npx xhs-cli <command>` - Run CLI commands directly
## Development Environment
### Prerequisites
- **Node.js**: >= 18.0.0 (see [package.json](mdc:package.json) engines)
- **TypeScript**: 5.0+ for compilation
- **Puppeteer**: For browser automation (auto-installed)
### Environment Variables
```bash
# Enable debug logging
export XHS_ENABLE_LOGGING=true
# Set log level
export XHS_LOG_LEVEL=DEBUG
# Browser configuration
export XHS_HEADLESS=false
export XHS_BROWSER_TIMEOUT=60000
# Server configuration
export XHS_PORT=3000
export XHS_HOST=127.0.0.1
```
## File Structure
### Source Files
- **TypeScript source**: `src/` directory
- **Entry point**: [src/index.ts](mdc:src/index.ts)
- **CLI**: [src/cli/xhs-cli.ts](mdc:src/cli/xhs-cli.ts)
- **Services**: `src/lib/` directory
- **Server**: `src/server/` directory
### Build Output
- **Compiled JavaScript**: `dist/` directory
- **Type definitions**: `dist/*.d.ts` files
- **Source maps**: `dist/*.js.map` files
### Configuration Files
- **TypeScript**: [tsconfig.json](mdc:tsconfig.json)
- **ESLint**: [eslint.config.js](mdc:eslint.config.js)
- **Package**: [package.json](mdc:package.json)
## Testing & Debugging
### MCP Server Testing
```bash
# Test stdio mode
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx xhs-cli mcp
# Test HTTP mode
npx xhs-cli mcp --mode http --port 3000
curl http://localhost:3000/health
```
### CLI Testing
```bash
# Test authentication
npx xhs-cli login --timeout 120
npx xhs-cli status
# Test browser setup
npx xhs-cli browser --with-deps
# Test content operations
npx xhs-cli feeds
npx xhs-cli search -k "test keyword"
```
### Debug Mode
```bash
# Enable minimal logging for debugging (errors and warnings only)
XHS_ENABLE_LOGGING=true npx xhs-cli mcp
XHS_ENABLE_LOGGING=true npx xhs-cli login
```
## Code Quality Standards
### TypeScript (Primary Language)
- **Strict mode enabled** - All strict TypeScript checks
- **Type safety first** - Comprehensive type coverage
- **ES2022 target** - Modern JavaScript features
- **ESNext modules** - ES module system
- **Declaration files** - Generate `.d.ts` files
- **Source maps** - Full debugging support
- **No implicit any** - Explicit typing required
### Linting
- **ESLint configuration** - TypeScript-specific rules
- **Prettier integration** - Code formatting
- **Import sorting** - Consistent import organization
- **Error prevention** - Catch common mistakes
### Build Process (TypeScript → JavaScript)
1. **Clean** - Remove previous build artifacts
2. **Type Check** - Validate TypeScript types and strict mode compliance
3. **Compile** - TypeScript compilation to JavaScript with declarations
4. **Source maps** - Generate debugging information for TypeScript source
5. **Output** - Place compiled JavaScript and `.d.ts` files in `dist/` directory
## Deployment
### NPM Package
- **Package name**: `xhs-mcp`
- **Version**: Managed in [package.json](mdc:package.json)
- **Files**: `dist/`, `README.md`, `docs/`
- **Binaries**: `xhs-cli` command
### Distribution
- **Main entry**: `dist/index.js`
- **CLI binary**: `dist/cli/xhs-cli.js`
- **Type definitions**: `dist/index.d.ts`
- **Source maps**: Included for debugging
