ReviewOS

also looking at this

stacks/ts-aax

chore: enhance logging

#55
Merged cab-mikee wants to merge chore/enhance-logging into main
12 files +379 -9

Review threads live on the whole diff, not on one commit, so none are shown here - a thread's line means something in the branch's final form, and painting it into an intermediate step would put it on code it is not about.

.cursor/rules/code-style.mdcadded+12-0
Changes to .cursor/rules/code-style.mdc
@@ -0,0 +1,12 @@
1---
2description: Code Style & Structure specifics
3globs:
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.mdcadded+9-0
Changes to .cursor/rules/documentation.mdc
@@ -0,0 +1,9 @@
1---
2description: Documentation specific rules
3globs: 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.mdcadded+11-0
Changes to .cursor/rules/error-handling.mdc
@@ -0,0 +1,11 @@
1---
2description: Error Handling and Validation specifics
3globs:
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.mdcadded+11-0
Changes to .cursor/rules/key-conventions.mdc
@@ -0,0 +1,11 @@
1---
2description: Key code conventions
3globs:
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.mdcadded+11-0
Changes to .cursor/rules/project-structure.mdc
@@ -0,0 +1,11 @@
1---
2description: Project structure information
3globs:
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.mdcadded+198-0
Changes to .cursor/rules/readme.mdc
@@ -0,0 +1,198 @@
1---
2description: General information based on the latest ./README.md content
3globs:
4---
5Update it if APIs change:
6
7# AAX Audio Converter
8
9A 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
25npm install -g @stacksjs/aax
26
27# Or use with npx
28npx @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
42aax convert /path/to/audiobook.aax
43```
44
45### Convert with custom options
46
47```bash
48aax convert /path/to/audiobook.aax --format m4b --output ./my-audiobooks --bitrate 192
49```
50
51### Convert and split by chapters
52
53```bash
54aax 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
76import { convertAAX } from 'aax'
77
78async 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
98You can create an `aax.config.ts` or `aax.config.js` file in your project root to customize default settings:
99
100```typescript
101export 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
136This 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
1401. 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
147Run the setup command:
148
149```bash
150aax setup-audible
151```
152
153This will:
154
1551. Check if the audible binary exists
1562. Make it executable
1573. Run the quickstart wizard (you'll need to follow the interactive prompts to log in to your Audible account)
1584. Retrieve your activation bytes from Audible's servers
1595. Save them for future use
160
161During the setup process, you'll see something like this:
162
163```
164Setting up Audible CLI and retrieving activation bytes...
165Note: You may be prompted to log in to your Audible account.
166Follow the prompts in the terminal to complete the setup.
167
168Attempting to get activation bytes from Audible CLI...
169Audible CLI is not configured. Setting up...
170Starting Audible CLI quickstart. Please follow the prompts to log in to your Audible account.
171# ... (interactive login process) ...
172
173Fetching activation bytes from Audible server...
174✅ Found activation bytes from Audible CLI: 2c******
175
176✅ Successfully retrieved activation bytes: 2c******
177
178You can now use this activation code with the convert command:
179aax convert your-audiobook.aax -c 2c1eeb0a
180
181The activation code has been saved and will be used automatically for future conversions.
182```
183
184Once 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
188If the automated setup fails, you can do it manually:
189
1901. Run: `./audible quickstart`
1912. Follow the prompts to log in to your Audible account
1923. Once set up, run: `./audible activation-bytes`
1934. Note the activation code (a 8-character hex string like `2c1eeb0a`)
1945. 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.mdcadded+9-0
Changes to .cursor/rules/syntax-formatting.mdc
@@ -0,0 +1,9 @@
1---
2description: Syntax and Formatting specifics
3globs:
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.mdcadded+10-0
Changes to .cursor/rules/testing.mdc
@@ -0,0 +1,10 @@
1---
2description: Testing specifics
3globs:
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.mdcadded+9-0
Changes to .cursor/rules/typescript.mdc
@@ -0,0 +1,9 @@
1---
2description: TypeScript Usage specifics
3globs: 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