Skip to content

Commit 34b4c8c

Browse files
cab-mikeecab-mikee
committed
chore: add clarity and cursor rules
1 parent fce23bb commit 34b4c8c

13 files changed

+567
-64
lines changed

‎.cursor/rules/code-style.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Code Style & Structure specifics
3+
globs:
4+
---
5+
## Code Style & Structure
6+
7+
- Write concise, technical TypeScript code with accurate examples in the docblock
8+
- If Bun native modules are available, use them
9+
- Use functional and declarative programming patterns; avoid classes unless needed
10+
- Prefer iteration and modularization over code duplication
11+
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)
12+
- Use proper jsdoc comments for functions, types, interfaces, and ensure examples are accurate

‎.cursor/rules/documentation.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Documentation specific rules
3+
globs: docs/**/*.md
4+
---
5+
## Documentation
6+
7+
- Write documentation for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./docs` directory is where the vitepress markdown documentation is stored
9+
- Make sure to update the docs markdown files

‎.cursor/rules/error-handling.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Error Handling and Validation specifics
3+
globs:
4+
---
5+
## Error Handling and Validation
6+
7+
- Prioritize error handling: handle errors and edge cases early
8+
- Use early returns and guard clauses
9+
- Implement proper error logging and user-friendly messages
10+
- Use error boundaries for unexpected errors
11+
- when `neverthrow` is available, ensure errors are typed

‎.cursor/rules/key-conventions.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Key code conventions
3+
globs:
4+
---
5+
## Key Conventions
6+
7+
- If there are two equally valid implementations, the browser version should be preferred
8+
- Aim for 100% test coverage
9+
- Avoid usage of `any`
10+
- Reuse eslint-ignore comments where present, unless not needed
11+
- ensure we log everything properly, including for debug reasons

‎.cursor/rules/project-structure.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Project structure information
3+
globs:
4+
---
5+
## Project Structure
6+
7+
- the `./src` directory is the source code
8+
- the `./test` directory is the test code
9+
- the `./bin` directory is the command-line code
10+
- you can also call the CLI via `./clarity ...`
11+
- the `./docs` directory is the documentation

‎.cursor/rules/readme.mdc‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
description: General information based on the latest ./README.md content
3+
globs:
4+
---
5+
Update it if APIs change:
6+
7+
# gitit
8+
9+
A powerful template and project scaffolding tool to help kick-start development of your next project.
10+
11+
## Features
12+
13+
Gitit comes with the following features:
14+
15+
- 🚀 **Fast Template Cloning** _Clone templates from GitHub, GitLab, Bitbucket, and more_
16+
- 💪 **Fully Typed APIs** _Written in TypeScript for a great developer experience_
17+
- 📦 **Zero Configuration** _Works out of the box with sensible defaults_
18+
- 🔄 **Offline Support** _Use cached templates when offline_
19+
- 🛠️ **Customizable** _Configure templates with various options_
20+
- 🧩 **Post-Installation Commands** _Run custom commands after cloning_
21+
- 🔑 **Private Repository Support** _Authentication for private templates_
22+
- 🖥️ **Interactive Shell** _Open a shell in your newly created project_
23+
24+
## Get Started
25+
26+
```bash
27+
# Install globally
28+
bun install -g @stacksjs/gitit
29+
30+
# or use directly with bunx
31+
bunx @stacksjs/gitit github:user/repo my-project
32+
```
33+
34+
## Usage
35+
36+
```bash
37+
# Basic usage
38+
gitit github:user/repo my-project
39+
40+
# With options
41+
gitit github:user/repo my-project --install --shell
42+
43+
# Clone with custom command
44+
gitit github:user/repo my-project --command "npm run dev"
45+
46+
# Use offline cached template
47+
gitit github:user/repo my-project --offline
48+
49+
# Clone to a specific directory
50+
gitit github:user/repo ./path/to/project
51+
```
52+
53+
## Available Options
54+
55+
| Option | Description |
56+
|--------|-------------|
57+
| `--force` | Clone to existing directory even if it exists |
58+
| `--force-clean` | Remove any existing directory or file recursively before cloning |
59+
| `--shell` | Open a new shell with current working directory |
60+
| `--install` | Install dependencies after cloning |
61+
| `--verbose` | Show verbose debugging info |
62+
| `--command` | Custom command to run after template is cloned |
63+
| `--auth` | Custom Authorization token for private repositories |
64+
| `--cwd` | Set current working directory to resolve dirs relative to it |
65+
| `--offline` | Do not attempt to download and use cached version |
66+
| `--prefer-offline` | Use cache if exists otherwise try to download |
67+
68+
## Library Usage
69+
70+
Gitit can also be used programmatically in your Node.js or Bun applications:
71+
72+
```js
73+
import { downloadTemplate } from '@stacksjs/gitit'
74+
75+
// Basic usage
76+
await downloadTemplate('github:user/repo')
77+
78+
// With options
79+
const result = await downloadTemplate('github:user/repo', {
80+
dir: './my-project',
81+
force: true,
82+
install: true,
83+
offline: false,
84+
preferOffline: true
85+
})
86+
87+
console.log(`Downloaded to ${result.dir}`)
88+
```
89+
90+
### API Reference
91+
92+
#### `downloadTemplate(source, options)`
93+
94+
The main function for downloading templates.
95+
96+
- **source**: `string` - Template source (e.g., "github:user/repo")
97+
- **options**: `DownloadTemplateOptions` - Configuration options
98+
99+
```ts
100+
interface DownloadTemplateOptions {
101+
provider?: string // Specify provider (github, gitlab, etc.)
102+
force?: boolean // Force clone even if directory exists
103+
forceClean?: boolean // Remove existing directory before cloning
104+
offline?: boolean // Use cached version only
105+
preferOffline?: boolean // Prefer cache if exists
106+
dir?: string // Target directory
107+
registry?: false | string // Registry URL or false to disable
108+
cwd?: string // Current working directory
109+
auth?: string // Auth token for private repositories
110+
install?: boolean // Install dependencies after download
111+
silent?: boolean // Hide installation output
112+
hooks?: Hooks // Custom lifecycle hooks
113+
}
114+
```
115+
116+
#### Return value
117+
118+
```ts
119+
interface DownloadTemplateResult {
120+
dir: string // The directory where template was extracted
121+
source: string // Original source string
122+
name: string // Template name
123+
tar: string // Tarball URL
124+
version?: string // Template version
125+
url?: string // Repository URL
126+
// ... additional properties
127+
}
128+
```
129+
130+
#### Advanced: Custom Plugins
131+
132+
You can extend gitit's functionality using plugins:
133+
134+
```js
135+
import { downloadTemplate } from '@stacksjs/gitit'
136+
137+
const myPlugin = {
138+
name: 'my-plugin',
139+
version: '1.0.0',
140+
hooks: {
141+
afterExtract: (result) => {
142+
console.log(`Template extracted to ${result.dir}`)
143+
return result
144+
}
145+
},
146+
providers: {
147+
myCustomSource: (input, options) => {
148+
// Custom template provider logic
149+
return {
150+
name: 'my-template',
151+
tar: 'https://example.com/template.tar.gz'
152+
}
153+
}
154+
}
155+
}
156+
157+
await downloadTemplate('mycustom:template', {
158+
plugins: [myPlugin]
159+
})
160+
```

‎.cursor/rules/syntax-formatting.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Syntax and Formatting specifics
3+
globs:
4+
---
5+
## Syntax and Formatting
6+
7+
- Use the "function" keyword for pure functions
8+
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
9+
- Make sure everything is properly commented

‎.cursor/rules/testing.mdc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
description: Testing specifics
3+
globs:
4+
---
5+
## Testing
6+
7+
- Write tests for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./test` directory is where the tests are stored
9+
- Use `bun test` to run the tests
10+
- Use bun native modules for testing from `import { x, y, z } from 'bun:test'`

‎.cursor/rules/typescript.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: TypeScript Usage specifics
3+
globs: docs/**/*.md
4+
---
5+
## TypeScript Usage
6+
7+
- Use TypeScript for all code; prefer interfaces over types
8+
- Avoid enums; use `maps` instead, or `as const`
9+
- Use functional components with TypeScript interfaces

0 commit comments

Comments
 (0)