Skip to content

Commit 8782381

Browse files
cab-mikeecab-mikee
authored
chore: enhance logging (#55)
* chore: enhance logging * chore: add cursor rules
1 parent c34c9c3 commit 8782381

12 files changed

+379
-9
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: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
description: General information based on the latest ./README.md content
3+
globs:
4+
---
5+
Update it if APIs change:
6+
7+
# AAX Audio Converter
8+
9+
A TypeScript library and CLI tool for converting Audible AAX audiobooks to standard MP3, M4A, or M4B formats.
10+
11+
![Screenshot](.github/art/screenshot.png)
12+
13+
## Features
14+
15+
- Convert AAX files to MP3, M4A, or M4B formats
16+
- Preserve chapter information
17+
- Automatically detect Audible activation code
18+
- Split audiobooks by chapters
19+
- Simple command-line interface
20+
21+
## Installation
22+
23+
```bash
24+
# Install globally
25+
npm install -g @stacksjs/aax
26+
27+
# Or use with npx
28+
npx @stacksjs/aax
29+
```
30+
31+
## Requirements
32+
33+
- `ffmpeg` & [`audible`](https://github.com/mkb79/audible-cli) must be installed and available in your PATH
34+
35+
_Please read [Using the Audible CLI Integration](#using-the-audible-cli-integration) for more information._
36+
37+
## CLI Usage
38+
39+
### Convert an AAX file to MP3
40+
41+
```bash
42+
aax convert /path/to/audiobook.aax
43+
```
44+
45+
### Convert with custom options
46+
47+
```bash
48+
aax convert /path/to/audiobook.aax --format m4b --output ./my-audiobooks --bitrate 192
49+
```
50+
51+
### Convert and split by chapters
52+
53+
```bash
54+
aax split /path/to/audiobook.aax
55+
```
56+
57+
### Available CLI Options
58+
59+
- `-o, --output <dir>` - Output directory (default: ./converted)
60+
- `-f, --format <format>` - Output format: mp3, m4a, m4b (default: mp3)
61+
- `-c, --code <code>` - Audible activation code (auto-detected if not provided)
62+
- `--chapters` - Preserve chapter information (default: true)
63+
- `-b, --bitrate <kbps>` - Audio bitrate in kbps (default: 'source' to match the original file)
64+
- `-v, --verbose` - Enable verbose logging
65+
- `--flat-folder-structure` - Use flat folder structure
66+
- `--series-title-in-folder-structure` - Include series title in folder structure
67+
- `--variable-bit-rate` - Apply variable bit rate
68+
- `--aac-encoding-44-1` - Fix AAC encoding for 44.1 kHz
69+
- `--use-named-chapters` - Use named chapters if available
70+
- `--skip-short-chapters-duration <seconds>` - Skip short chapters between book parts
71+
- `--skip-very-short-chapter-duration <seconds>` - Skip very short chapters at begin and end
72+
73+
## Library Usage
74+
75+
```typescript
76+
import { convertAAX } from 'aax'
77+
78+
async function convertBook() {
79+
const result = await convertAAX({
80+
inputFile: '/path/to/audiobook.aax',
81+
outputFormat: 'mp3',
82+
outputDir: './converted',
83+
chaptersEnabled: true,
84+
bitrate: 128,
85+
})
86+
87+
if (result.success) {
88+
console.log(`Conversion complete: ${result.outputPath}`)
89+
}
90+
else {
91+
console.error(`Conversion failed: ${result.error}`)
92+
}
93+
}
94+
```
95+
96+
## Configuration
97+
98+
You can create an `aax.config.ts` or `aax.config.js` file in your project root to customize default settings:
99+
100+
```typescript
101+
export default {
102+
verbose: true,
103+
outputFormat: 'mp3',
104+
outputDir: './my-audiobooks',
105+
chaptersEnabled: true,
106+
bitrate: 192,
107+
// Optional: manually set the activation code
108+
// activationCode: '1a2b3c4d',
109+
// Optional: specify a custom FFmpeg path
110+
// ffmpegPath: '/usr/local/bin/ffmpeg',
111+
// New options
112+
flatFolderStructure: false,
113+
seriesTitleInFolderStructure: true,
114+
fullCaptionForBookFolder: false,
115+
partFolderPrefix: 'standard',
116+
sequenceNumberDigits: 2,
117+
customSearchWords: [],
118+
additionalPunctuation: '',
119+
intermediateFileCopy: false,
120+
aacEncoding44_1: false,
121+
variableBitRate: false,
122+
reduceBitRate: 'no',
123+
fileType: 'm4a',
124+
useISOLatin1: false,
125+
extractCoverImage: true,
126+
useNamedChapters: true,
127+
skipShortChaptersDuration: 25,
128+
skipVeryShortChapterDuration: 10,
129+
verifyChapterMarks: 'all',
130+
preferEmbeddedChapterTimes: true,
131+
}
132+
```
133+
134+
## Using the Audible CLI Integration
135+
136+
This tool integrates with the Audible CLI to automatically retrieve activation bytes (activation codes) from Audible's servers using your account credentials. This makes it much easier to convert your AAX audiobooks without manually finding activation codes.
137+
138+
### Prerequisites
139+
140+
1. Download the Audible CLI binary and place it in the root of your project:
141+
- [Audible CLI Releases](https://github.com/mkb79/audible-cli/releases)
142+
- Choose the appropriate version for your OS (e.g., `audible-cli-0.2.0-windows-amd64.exe` for Windows)
143+
- Rename it to `audible` and place it in the project root
144+
145+
### Setting up Audible CLI
146+
147+
Run the setup command:
148+
149+
```bash
150+
aax setup-audible
151+
```
152+
153+
This will:
154+
155+
1. Check if the audible binary exists
156+
2. Make it executable
157+
3. Run the quickstart wizard (you'll need to follow the interactive prompts to log in to your Audible account)
158+
4. Retrieve your activation bytes from Audible's servers
159+
5. Save them for future use
160+
161+
During the setup process, you'll see something like this:
162+
163+
```
164+
Setting up Audible CLI and retrieving activation bytes...
165+
Note: You may be prompted to log in to your Audible account.
166+
Follow the prompts in the terminal to complete the setup.
167+
168+
Attempting to get activation bytes from Audible CLI...
169+
Audible CLI is not configured. Setting up...
170+
Starting Audible CLI quickstart. Please follow the prompts to log in to your Audible account.
171+
# ... (interactive login process) ...
172+
173+
Fetching activation bytes from Audible server...
174+
✅ Found activation bytes from Audible CLI: 2c******
175+
176+
✅ Successfully retrieved activation bytes: 2c******
177+
178+
You can now use this activation code with the convert command:
179+
aax convert your-audiobook.aax -c 2c1eeb0a
180+
181+
The activation code has been saved and will be used automatically for future conversions.
182+
```
183+
184+
Once set up, your activation code will be automatically used for all future conversions, so you don't need to specify it manually.
185+
186+
### Manual Setup (if the automated setup fails)
187+
188+
If the automated setup fails, you can do it manually:
189+
190+
1. Run: `./audible quickstart`
191+
2. Follow the prompts to log in to your Audible account
192+
3. Once set up, run: `./audible activation-bytes`
193+
4. Note the activation code (a 8-character hex string like `2c1eeb0a`)
194+
5. Use this code with the convert command:
195+
196+
```bash
197+
aax convert your-audiobook.aax -c YOUR_ACTIVATION_CODE
198+
```

‎.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

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070
"buddy-bot": "^0.9.7",
7171
"bumpp": "^10.1.0",
7272
"bun-git-hooks": "^0.2.19",
73-
"bun-plugin-dtsx": "^0.21.12",\
73+
"bun-plugin-dtsx": "^0.21.12",
7474
"bunfig": "^0.8.5",
7575
"changelogen": "^0.6.2",
7676
"typescript": "^5.9.2"

0 commit comments

Comments
 (0)