From 36263168981f153a33881e1c327adbd55e7b9912 Mon Sep 17 00:00:00 2001 From: rosendo Date: Sun, 13 Apr 2025 01:18:57 +0800 Subject: [PATCH 1/4] doc: Update README.md to include npm CLI setup instructions and requirements --- readme.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 49f02e72..a2224dd2 100644 --- a/readme.md +++ b/readme.md @@ -49,7 +49,21 @@ This template dramatically improves AI workflows in Agent and Custom mode by pro ## Quick Start Options -### A) New Project Setup +### A) npm cli + +#### πŸ›  Requirements + +- Node.js >= 22.14.0 + +#### πŸ“₯ Installation & Usage + +```bash +npx cursor-rules-deploy /path/to/your/project +``` + +For more usage examples, refer to [cursor-rules-deploy](https://github.com/rosendolu/cursor-rules-deploy#readme) + +### B) New Project Setup Start a new project with the Agile Workflow and Rules Generator: @@ -67,7 +81,7 @@ cd cursor-auto-rules-agile-workflow The script creates your project folder (if needed) with all rules, documentation, and configuration files to start with the agile workflow. -### B) Add to Existing Project +### C) Add to Existing Project Enhance your current project with the rules generator: From 9a065c25095c7aa37dc7ede7caea8ea837ba355d Mon Sep 17 00:00:00 2001 From: rosendo Date: Wed, 16 Apr 2025 23:09:12 +0800 Subject: [PATCH 2/4] feat: add new rules and guidelines for dependency management, API integration, and translation processes --- .cursor/mcp.json | 7 + .../dependency-version-constraints-auto.mdc | 73 ++++++++++ .../lib-generating-agent-manual.mdc | 94 +++++++++++++ .../node-version-management-manual.mdc | 92 +++++++++++++ .../core-rules/rule-generating-agent.mdc | 2 +- .../emoji-communication-always.mdc | 71 +++++++--- .../tool-rules/apifox-integration-manual.mdc | 126 ++++++++++++++++++ .../translation-extraction-manual.mdc | 32 +++++ .../translations-to-table-manual.mdc | 54 ++++++++ 9 files changed, 535 insertions(+), 16 deletions(-) create mode 100644 .cursor/rules/core-rules/dependency-version-constraints-auto.mdc create mode 100644 .cursor/rules/core-rules/lib-generating-agent-manual.mdc create mode 100644 .cursor/rules/core-rules/node-version-management-manual.mdc create mode 100644 .cursor/rules/tool-rules/apifox-integration-manual.mdc create mode 100644 .cursor/rules/translations/translation-extraction-manual.mdc create mode 100644 .cursor/rules/translations/translations-to-table-manual.mdc diff --git a/.cursor/mcp.json b/.cursor/mcp.json index 495b9535..48e0e077 100644 --- a/.cursor/mcp.json +++ b/.cursor/mcp.json @@ -8,6 +8,13 @@ "-y", "tavily-mcp@0.1.3" ] + }, + "api fox docs": { + "command": "npx", + "args": ["-y", "apifox-mcp-server@latest", "--project="], + "env": { + "APIFOX_ACCESS_TOKEN": "" + } } } } diff --git a/.cursor/rules/core-rules/dependency-version-constraints-auto.mdc b/.cursor/rules/core-rules/dependency-version-constraints-auto.mdc new file mode 100644 index 00000000..a543cc62 --- /dev/null +++ b/.cursor/rules/core-rules/dependency-version-constraints-auto.mdc @@ -0,0 +1,73 @@ +# πŸ“¦ Dependency and Version Constraints + +## Critical Rules + +- πŸ”’ Lock all direct dependency versions to specific versions or exact ranges to ensure reproducible builds +- 🚫 Never use loose version constraints (e.g., ^, ~, >=, >) in production dependencies +- ⚑ Specify Node.js version constraints in package.json using the engines field +- πŸ”„ Keep all dependencies up to date with security patches while maintaining version locks +- πŸ—οΈ Separate devDependencies from production dependencies in Node.js projects +- πŸ“ Document any specific version requirements or compatibility issues in README.md +- πŸ§ͺ Test the application with the exact versions specified in lock files +- πŸ” Review all transitive dependencies for security vulnerabilities +- πŸ“Š Maintain compatibility with the following version constraints: + - Node.js: >= 18.x (LTS) + - Python: >= 3.8 + - .NET Core: >= 6.0 + - Java: >= 11 + - Ruby: >= 3.0 +- 🚨 Flag any dependencies that require specific OS or architecture support + +## Examples + + + # package.json + { + "name": "my-app", + "version": "1.0.0", + "engines": { + "node": ">=18.0.0" + }, + "dependencies": { + "express": "4.18.2", + "react": "18.2.0", + "typescript": "5.0.4" + }, + "devDependencies": { + "jest": "29.5.0", + "eslint": "8.40.0" + } + } + + # requirements.txt + fastapi==0.95.2 + sqlalchemy==2.0.15 + pydantic==1.10.7 + + # pom.xml + + 11 + 2.7.11 + + + + + # package.json + { + "dependencies": { + "express": "^4.18.2", + "react": "~18.2.0", + "typescript": ">=5.0.0" + } + } + + # requirements.txt + fastapi>=0.95.2 + sqlalchemy + pydantic>=1.10.0 + + # pom.xml + + LATEST + + \ No newline at end of file diff --git a/.cursor/rules/core-rules/lib-generating-agent-manual.mdc b/.cursor/rules/core-rules/lib-generating-agent-manual.mdc new file mode 100644 index 00000000..a9d98f3d --- /dev/null +++ b/.cursor/rules/core-rules/lib-generating-agent-manual.mdc @@ -0,0 +1,94 @@ +--- +description: Library and Dependency Management Guidelines. +globs: +alwaysApply: false +--- + + +# πŸ“¦ Library and Dependency Management Guidelines + +## Critical Rules + +- πŸ” Dependency Analysis + - Extract and analyze all dependencies from `package.json` + - Check Node.js version from `.nvmrc` first, fallback to `package.json` engines field + - Maintain a clear understanding of each dependency's purpose and version constraints + - Track peer dependencies and their compatibility + +- πŸš€ Node.js Version Management + - Always respect the Node.js version specified in `.nvmrc` or `package.json` + - Utilize latest ECMAScript features available for the specified Node.js version + - Document any version-specific features or syntax being used + - Ensure all dependencies are compatible with the specified Node.js version + +- πŸ“Š Version Compatibility + - Implement features based on the available dependency versions + - Check API compatibility before using new features from dependencies + - Follow semantic versioning guidelines for dependency updates + - Document any breaking changes or version-specific implementations + +## Examples + + + # Valid Implementation Example + + # .nvmrc + 18.19.0 + + # package.json + { + "name": "my-project", + "engines": { + "node": ">=18.19.0" + }, + "dependencies": { + "express": "^4.18.0", + "typescript": "^5.0.0" + } + } + + # Implementation using Node.js 18 features + const data = await fetch('https://api.example.com/data'); + const result = await data.json(); + + // Using Express 4.18 features + app.use(express.json({ limit: '10mb' })); + + // Using TypeScript 5.0 features + const config = { + port: 3000, + host: 'localhost' + } as const; + + + + # Invalid Implementation Example + + # .nvmrc + 16.14.0 + + # package.json + { + "name": "my-project", + "engines": { + "node": ">=16.14.0" + }, + "dependencies": { + "express": "^4.17.0", + "typescript": "^4.5.0" + } + } + + # Implementation using incompatible features + // ❌ Using fetch without polyfill (not available in Node.js 16) + const data = await fetch('https://api.example.com/data'); + + // ❌ Using TypeScript 5.0 features with TypeScript 4.5 + const config = { + port: 3000, + host: 'localhost' + } satisfies Config; + + // ❌ Using Express middleware options not available in 4.17 + app.use(express.json({ limit: '10mb', strict: false })); + \ No newline at end of file diff --git a/.cursor/rules/core-rules/node-version-management-manual.mdc b/.cursor/rules/core-rules/node-version-management-manual.mdc new file mode 100644 index 00000000..339a2abb --- /dev/null +++ b/.cursor/rules/core-rules/node-version-management-manual.mdc @@ -0,0 +1,92 @@ +# πŸ”§ Node.js Version Management Guidelines + +## Critical Rules + +- πŸ“‹ Version Detection Priority + - MUST check version in following order: + 1. `.nvmrc` file in project root + 2. `engines.node` field in `package.json` + 3. Default to latest LTS if neither exists + +- πŸ”’ Version Enforcement + - Enforce exact Node.js version match with `.nvmrc` + - Use `>=` in package.json engines field for minimum version requirement + - Document Node.js version requirements in project README.md + - Add version check in project's start/build scripts + +- πŸš€ Feature Compatibility + - Only use JavaScript features supported by specified Node.js version + - Document any version-specific features in code comments + - Include polyfills for features not available in target Node.js version + - Test application in both minimum and latest supported Node.js versions + +- βš™οΈ Development Environment + - Use `nvm` or similar tool for version management + - Set up CI/CD to test against specified Node.js version + - Include version check in development setup scripts + - Document version switching instructions in README.md + +## Examples + + + # Valid Project Setup Example + + # .nvmrc + 18.19.0 + + # package.json + { + "name": "my-project", + "engines": { + "node": ">=18.19.0" + }, + "scripts": { + "prestart": "node scripts/check-node-version.js", + "start": "node index.js" + } + } + + # scripts/check-node-version.js + const semver = require('semver'); + const { engines } = require('./package.json'); + const version = engines.node; + + if (!semver.satisfies(process.version, version)) { + console.error( + `Required node version ${version} not satisfied with current version ${process.version}.` + ); + process.exit(1); + } + + # README.md + ## Requirements + - Node.js version: 18.19.0 (LTS) + - Use `nvm use` to automatically switch to the correct version + + + + # Invalid Project Setup Example + + # Missing .nvmrc file + + # package.json (❌ Incorrect version specification) + { + "name": "my-project", + "engines": { + "node": "18.19.0" // ❌ Using exact version instead of >= + }, + "scripts": { + "start": "node index.js" // ❌ No version check + } + } + + # index.js (❌ Using features without version check) + // Using features without checking Node.js version compatibility + const { fetch } = globalThis; // ❌ No version check or polyfill + + // ❌ No documentation about version requirements + const data = await fetch('https://api.example.com/data'); + + // ❌ Using new features without fallback + const config = structuredClone(defaultConfig); + \ No newline at end of file diff --git a/.cursor/rules/core-rules/rule-generating-agent.mdc b/.cursor/rules/core-rules/rule-generating-agent.mdc index d9accb79..2d17594b 100644 --- a/.cursor/rules/core-rules/rule-generating-agent.mdc +++ b/.cursor/rules/core-rules/rule-generating-agent.mdc @@ -5,7 +5,7 @@ alwaysApply: true --- # Cursor Rules Format -## Template Structure for Rules Files +## Template Structure for Rules Files(FrontMatter must include in new generated rules) ```mdc --- diff --git a/.cursor/rules/global-rules/emoji-communication-always.mdc b/.cursor/rules/global-rules/emoji-communication-always.mdc index 82c5bdd8..ee28dc77 100644 --- a/.cursor/rules/global-rules/emoji-communication-always.mdc +++ b/.cursor/rules/global-rules/emoji-communication-always.mdc @@ -8,26 +8,67 @@ alwaysApply: true ## Critical Rules - - Use emojis purposefully to enhance meaning, but feel free to be creative and fun - - Place emojis at the end of statements or sections - - Maintain professional tone while surprising users with clever choices - - Limit emoji usage to 1-2 per major section - - Choose emojis that are both fun and contextually appropriate - - Place emojis at the end of statements, not at the beginning or middle - - Don't be afraid to tell a mini-story with your emoji choice +- Use emojis sparingly and purposefully to enhance readability and engagement +- Place emojis at the beginning of sections, headings, or key points for visual hierarchy +- Choose emojis that are universally recognizable and relevant to the technical context +- Maintain consistency in emoji usage throughout the documentation +- Never use emojis to replace critical technical terms or important information +- Limit to one emoji per heading/point to avoid visual clutter +- Use emojis primarily for: + - πŸ“š Documentation sections and categories + - ⚠️ Important warnings or notices + - πŸ’‘ Tips and best practices + - 🎯 Goals and objectives + - ✨ New features or highlights + - πŸ”§ Configuration and setup + - πŸ› Bug fixes and known issues + - πŸ”’ Security-related information + - πŸš€ Performance improvements + - πŸ“ Examples and code snippets ## Examples - "I've optimized your database queries πŸƒβ€β™‚οΈ" - "Your bug has been squashed πŸ₯ΎπŸ›" - "I've cleaned up the legacy code 🧹✨" - "Fixed the performance issue πŸŒβž‘οΈπŸ†" +# πŸ“˜ Project Documentation + +## 🎯 Project Goals +- Build a scalable microservice architecture +- Implement robust security measures +- Optimize application performance + +## ⚠️ Prerequisites +- Node.js 18.x or higher +- Docker Desktop +- MongoDB + +## πŸ’‘ Quick Start +1. Clone the repository +2. Install dependencies +3. Run setup script + +## πŸ”§ Configuration +Detailed steps for configuring your development environment... + +## πŸ”’ Security Guidelines +Important security measures and best practices... - "Multiple πŸŽ‰ emojis 🎊 in 🌟 one message" - "Using irrelevant emojis πŸ₯‘" - "Placing the emoji in the middle ⭐️ of a sentence" - "Great Job!!!" - lack of obvious use of an emoji +# πŸ“˜ πŸš€ ✨ Project Documentation + +## Project Goals 🎯 πŸ’ͺ πŸ’― +- Build a scalable microservice architecture πŸ—οΈ +- Implement robust security measures πŸ”’ +- Optimize application performance πŸš€ + +## Prerequisites ⚠️ ❗ ❕ +- Node.js 18.x or higher πŸ’» +- Docker Desktop 🐳 +- MongoDB πŸ—„οΈ + +## Quick Start πŸƒ πŸ’¨ +1. Clone the repository πŸ“₯ +2. Install dependencies ⚑ +3. Run setup script πŸ”„ + diff --git a/.cursor/rules/tool-rules/apifox-integration-manual.mdc b/.cursor/rules/tool-rules/apifox-integration-manual.mdc new file mode 100644 index 00000000..441ead3a --- /dev/null +++ b/.cursor/rules/tool-rules/apifox-integration-manual.mdc @@ -0,0 +1,126 @@ +# API Fox Integration Guidelines + +## Critical Rules + +- All API documentation must be synchronized with API Fox documentation +- API implementation must strictly follow the API Fox documentation specifications +- Response types must be generated based on API Fox documentation examples +- API endpoints must match exactly with the paths defined in API Fox +- Version control of API documentation must be maintained through API Fox +- Use API Fox as the single source of truth for API specifications + +### File Structure +- Each API module must contain at minimum: + - `hooks.ts`: Contains all API hook implementations + - `types.ts`: Contains all TypeScript interfaces and types +- Additional files like `constants.ts` or `utils.ts` can be added as needed + +### TypeScript Guidelines +- Maximize type reuse through TypeScript utility types (Pick, Omit, Partial, etc.) +- Use interface composition over repetition +- Common patterns to follow: + - Request params: `interface I{ModuleName}{Action}Params` + - Response types: `interface I{ModuleName}{Action}Response` + - List types: `type T{Entity}List = Array` +- Place shared types in a common types.ts file + +### Response Handling +- API response types must always correspond to the `data` field of the response +- Generic type parameter in `useQuery` should match the expected data structure +- Use type assertions sparingly and only when necessary + +## Examples + + +import {isNil} from 'lodash' +import { useMutation, UseMutationResult, useQuery, UseQueryResult } from '@tanstack/react-query'; +import { + IChatLogQueryParams, + IChatLogResponse, + ISopCategory, + ISopCategoryParams, + ISopDocument, + ISopDocumentListParams, + ISopDocumentListResponse, + ISopSaveCategoryParams, + ISopSaveDocumentParams, +} from './types'; + + // types.ts + interface IBaseResponse { + code: number; + message: string; + data: T; + } + + interface IChatMessage { + id: string; + content: string; + timestamp: number; + } + + // Reusing types with utility types + type TChatMessageList = Array; + type TChatMessagePartial = Partial; + + interface IChatLogQueryParams { + startTime: number; + endTime: number; + userId?: string; + } + + interface IChatLogResponse { + messages: TChatMessageList; + total: number; + } + + // hooks.ts + export const useGetDetailList = (params: IChatLogQueryParams) => { + return useQuery({ + queryKey: ['chat-log-chat-list', params], + refetchOnWindowFocus: false, + queryFn: () => + request({ + url: '/cs/service/get_im_service_chat_list', + method: 'POST', + data: params, + }), + enabled: !isNil(params), + staleTime: 6e5, + }); + }; + + + + // Invalid: Missing types file + // Direct implementation in hooks without separate types + + // Invalid: Not reusing types + interface IUserListResponse { + users: Array<{ + id: string; + name: string; + }>; + total: number; + } + + interface IGroupListResponse { + groups: Array<{ + id: string; + name: string; + }>; + total: number; + } + + // Invalid: Incorrect response type handling + export const useGetUsers = (params: IUserListParams) => { + return useQuery({ // Missing generic type parameter + queryKey: ['users', params], + queryFn: () => request({ + url: '/api/users', + method: 'GET', + params, + }).then(res => res), // Not extracting data field + }); + }; + \ No newline at end of file diff --git a/.cursor/rules/translations/translation-extraction-manual.mdc b/.cursor/rules/translations/translation-extraction-manual.mdc new file mode 100644 index 00000000..722407bf --- /dev/null +++ b/.cursor/rules/translations/translation-extraction-manual.mdc @@ -0,0 +1,32 @@ +--- +description: "Translation Extraction and Key Generation" +globs: {@folder}/**/*.tsx +alwaysApply: false +--- + +# Translation Extraction and Key Generation + +## Critical Rules + +- When processing `.tsx` files for translation: + 1. Extract all `t('value')` calls where value doesn't start with a prefix + 2. Generate normalized keys using camelCase without special characters (max 12 chars) + 3. Maintain original text as translation value in JSON files + 4. Preserve duplicate `t()` calls with same generated key + 5. Require user to provide prefix in format `{prefix}.{sub}` before processing + 6. Update both source files and translation JSONs atomically + +## Examples + + +Valid replacement: +Original: t('user profile') +Generated: t('support.tl.userProfile') +JSON entry: "support.tl.userProfile": "user profile" + + + +Invalid key: t('user_profile') +Invalid length: t('support.tl.thisIsWayTooLongForKey') +Missing prefix: t('user') + \ No newline at end of file diff --git a/.cursor/rules/translations/translations-to-table-manual.mdc b/.cursor/rules/translations/translations-to-table-manual.mdc new file mode 100644 index 00000000..5ff4f945 --- /dev/null +++ b/.cursor/rules/translations/translations-to-table-manual.mdc @@ -0,0 +1,54 @@ +--- +description: "JSON Translation to Table Format Rule" +globs: +alwaysApply: false +--- + +# JSON Translation to Table Format Rule + +## Critical Rules + +- Input must be a JSON with key-value pairs where: + - Keys follow the format `{prefix}.{sub}` + - Values are English text that will be preserved as-is + +- Processing Requirements: + - Parse all `"key": "value"` pairs from JSON input + - Filter out keys that don't match the `{prefix}.` pattern (skip if no prefix specified) + - Generate Chinese translations for English value content + +- Output Table Format: + - Must use CSV-style format with 3 columns + - First row must be the header: `key,θ‹±ζ–‡,δΈ­ζ–‡` + - Each subsequent row follows: `{original_key},{english_value},{chinese_translation}` + - Maintain original key ordering from input JSON + +## Examples + + +Input JSON: +{ + "common.welcome": "Welcome to our platform", + "error.notFound": "Page not found", + "invalid_key": "This will be filtered out" +} + +Output Table: +key,θ‹±ζ–‡,δΈ­ζ–‡ +common.welcome,Welcome to our platform,欒迎ζ₯εˆ°ζˆ‘δ»¬ηš„εΉ³ε° +error.notFound,Page not found,鑡青ζœͺζ‰Ύεˆ° + + + +// Missing required columns +key,θ‹±ζ–‡ +common.welcome,Welcome to our platform + +// Incorrect column order +θ‹±ζ–‡,key,δΈ­ζ–‡ +Welcome to our platform,common.welcome,欒迎ζ₯εˆ°ζˆ‘δ»¬ηš„εΉ³ε° + +// Invalid key format (missing prefix structure) +key,θ‹±ζ–‡,δΈ­ζ–‡ +welcome,Welcome to our platform,欒迎ζ₯εˆ°ζˆ‘δ»¬ηš„εΉ³ε° + \ No newline at end of file From 8ef935dfd897a7a8360405bcfb453ce6024dd3e5 Mon Sep 17 00:00:00 2001 From: rosendo Date: Wed, 16 Apr 2025 23:14:05 +0800 Subject: [PATCH 3/4] chore: remove Node.js version management guidelines document --- .../node-version-management-manual.mdc | 92 ------------------- 1 file changed, 92 deletions(-) delete mode 100644 .cursor/rules/core-rules/node-version-management-manual.mdc diff --git a/.cursor/rules/core-rules/node-version-management-manual.mdc b/.cursor/rules/core-rules/node-version-management-manual.mdc deleted file mode 100644 index 339a2abb..00000000 --- a/.cursor/rules/core-rules/node-version-management-manual.mdc +++ /dev/null @@ -1,92 +0,0 @@ -# πŸ”§ Node.js Version Management Guidelines - -## Critical Rules - -- πŸ“‹ Version Detection Priority - - MUST check version in following order: - 1. `.nvmrc` file in project root - 2. `engines.node` field in `package.json` - 3. Default to latest LTS if neither exists - -- πŸ”’ Version Enforcement - - Enforce exact Node.js version match with `.nvmrc` - - Use `>=` in package.json engines field for minimum version requirement - - Document Node.js version requirements in project README.md - - Add version check in project's start/build scripts - -- πŸš€ Feature Compatibility - - Only use JavaScript features supported by specified Node.js version - - Document any version-specific features in code comments - - Include polyfills for features not available in target Node.js version - - Test application in both minimum and latest supported Node.js versions - -- βš™οΈ Development Environment - - Use `nvm` or similar tool for version management - - Set up CI/CD to test against specified Node.js version - - Include version check in development setup scripts - - Document version switching instructions in README.md - -## Examples - - - # Valid Project Setup Example - - # .nvmrc - 18.19.0 - - # package.json - { - "name": "my-project", - "engines": { - "node": ">=18.19.0" - }, - "scripts": { - "prestart": "node scripts/check-node-version.js", - "start": "node index.js" - } - } - - # scripts/check-node-version.js - const semver = require('semver'); - const { engines } = require('./package.json'); - const version = engines.node; - - if (!semver.satisfies(process.version, version)) { - console.error( - `Required node version ${version} not satisfied with current version ${process.version}.` - ); - process.exit(1); - } - - # README.md - ## Requirements - - Node.js version: 18.19.0 (LTS) - - Use `nvm use` to automatically switch to the correct version - - - - # Invalid Project Setup Example - - # Missing .nvmrc file - - # package.json (❌ Incorrect version specification) - { - "name": "my-project", - "engines": { - "node": "18.19.0" // ❌ Using exact version instead of >= - }, - "scripts": { - "start": "node index.js" // ❌ No version check - } - } - - # index.js (❌ Using features without version check) - // Using features without checking Node.js version compatibility - const { fetch } = globalThis; // ❌ No version check or polyfill - - // ❌ No documentation about version requirements - const data = await fetch('https://api.example.com/data'); - - // ❌ Using new features without fallback - const config = structuredClone(defaultConfig); - \ No newline at end of file From 6a85dca1ee58eb30728650c7c00728daaf6bb3b0 Mon Sep 17 00:00:00 2001 From: rosendo Date: Wed, 16 Apr 2025 23:20:50 +0800 Subject: [PATCH 4/4] feat: add NPM package publishing guidelines and update rule template structure --- .../core-rules/rule-generating-agent.mdc | 2 +- .../rules/tool-rules/npm-publish-agent.mdc | 69 +++++++++++++++++++ 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 .cursor/rules/tool-rules/npm-publish-agent.mdc diff --git a/.cursor/rules/core-rules/rule-generating-agent.mdc b/.cursor/rules/core-rules/rule-generating-agent.mdc index 2d17594b..8e52cdce 100644 --- a/.cursor/rules/core-rules/rule-generating-agent.mdc +++ b/.cursor/rules/core-rules/rule-generating-agent.mdc @@ -5,7 +5,7 @@ alwaysApply: true --- # Cursor Rules Format -## Template Structure for Rules Files(FrontMatter must include in new generated rules) +## Template Structure for Rules Files (FrontMatter must include in new generated rules) ```mdc --- diff --git a/.cursor/rules/tool-rules/npm-publish-agent.mdc b/.cursor/rules/tool-rules/npm-publish-agent.mdc new file mode 100644 index 00000000..a10ec2a4 --- /dev/null +++ b/.cursor/rules/tool-rules/npm-publish-agent.mdc @@ -0,0 +1,69 @@ +--- +description: NPM Package Publishing Guidelines +globs: +alwaysApply: false +--- + + + +# NPM Package Publishing Guidelines + +## Critical Rules + +- πŸ§ͺ Always run tests before publishing + - All tests must pass successfully + - Fail the publishing process if any test fails + +- πŸ—οΈ Build process must be completed + - Run the build command specified in package.json + - Verify build artifacts are generated correctly + - Fail if build process encounters errors + +- πŸ“¦ Version management + - Version must be updated using npm version command + - Only accept valid semver increments: major, minor, or patch + - Version bump must be committed to git + +- πŸš€ Publishing process + - Verify user is logged in to npm + - Ensure package.json is properly configured + - Run npm publish only after all previous steps succeed + - Verify successful publication via npm view + +## Examples + + + # βœ… Valid Publishing Workflow + + # 1. Run tests + npm test # All tests pass + + # 2. Build package + npm run build # Build succeeds + + # 3. Update version (interactive) + npm version patch # Version updated to 1.0.1 + + # 4. Publish package + npm publish # Package published successfully + + + + # ❌ Invalid Publishing Workflow + + # Skipping tests and directly publishing + npm publish + + # Publishing without version update + npm run build + npm publish + + # Publishing with failed tests + npm test # Tests failed + npm version minor + npm publish + + # Wrong version update format + npm version 1.0.1 # Direct version number instead of semver keyword + npm publish + \ No newline at end of file