audnexus

Imported from laxamentumtech/audnexus (AGENTS.md). Install upstream with npx skills add laxamentumtech/audnexus. Copyright stays with the author.

Repository Standards for AI Agents

This document establishes comprehensive standards for AI agents working on the audnexus project. All agents must follow these guidelines to ensure consistency, quality, and maintainability.

1. Testing Standards

1.1 Unit Test Requirements

All code changes must include appropriate unit tests. Tests are located in the tests/ directory and follow the naming patterns:

• Test file pattern: **/*.+(spec|test).+(ts|tsx|js)
• Location: tests/**/*.+(ts|tsx|js)
• Live tests excluded: tests/live/ (see Section 6)

Run unit tests:

bun run test

This command executes Bun's test runner with the following options:

• --timeout 30000: Sets per-test timeout to 30 seconds
• Runs only Bun-compatible tests (subset of total test suite during migration)

Note: Some legacy tests use Jest-specific APIs (jest.mock(), jest-mock-extended) and are not included in the default test command. These tests are being converted to use Bun's native testing APIs. New tests should use Bun's native mocking capabilities.

1.2 Coverage

Coverage reports are generated automatically by Bun test. Coverage configuration is defined in bunfig.toml.

Coverage reports are generated in: coverage/ directory

1.3 Mock Guidelines

Recommended approach: Use Bun's native mocking capabilities or simple function stubs.

Example of Bun-compatible mock:

import { mock } from 'bun:test'

// Example: Mocking a simple function
const mockFetch = mock(() => Promise.resolve({ data: 'test' }))

1.4 Test Execution Commands

2. Code Quality Standards

2.1 TypeScript Configuration

The project uses TypeScript 5.9.3 with strict mode enabled. See tsconfig.json. Build command:

bun run build-ts  # or bun run build (includes build-ts)

2.2 ESLint Rules

The project uses ESLint 10.0.0 with the following configuration (eslint.config.mjs):

Extended configs:

• eslint:recommended
• plugin:@typescript-eslint/recommended
• prettier

Custom rules:

Import sort order: Use simple-import-sort/imports rule via bun run lint.

Run linting:

bun run lint

This runs:

1. Prettier check: prettier --config .prettierrc --check 'src/**/*.ts'
2. TypeScript check: tsc --noEmit
3. ESLint: eslint "**/*.{js,ts}" --quiet --fix

2.3 Prettier Configuration

Format code:

bun run format

2.4 Module Aliases

The project uses module aliases (#helpers/*, #config/*, #static/*, etc., defined in package.json).

3. Dependency Management

3.1 Update Process

Standard update workflow:

# 1. Check for outdated packages
bun outdated

# 2. Update dependencies
bun update

# 3. Install new dependencies
bun install

# 4. Run full verification
bun run lint && bun run test && bun run build

3.2 Major Version Handling

Major version updates require special attention.

Breaking change detection checklist:

1. Review the package's CHANGELOG or release notes
2. Check for peer dependency warnings
3. Look for deprecated API usage warnings
4. Run bun run test to verify all tests pass
5. Check bun run build compiles without errors

3.3 Security Patch SLA

Priority levels:

Check for vulnerabilities:

bun audit

3.4 Rollback Procedures

If a dependency update causes issues:

# 1. Revert package.json and bun.lock changes
git checkout package.json bun.lock
# 2. Reinstall previous versions
bun install
# 3. Verify restoration
bun run lint && bun run test && bun run build

4. CI/CD Standards

4.1 What Runs in CI

Bun CI Workflow (.github/workflows/bun.yml):

Triggers:

• Push to main, develop, renovate/* branches
• Pull requests to main, develop
• Scheduled: Every Monday at 13:00 UTC

Steps:

bun install
bun run lint
bun run test
bun run build

4.2 Required Checks

All pull requests must pass:

4.3 Failure Handling

On CI failure:

1. Check the workflow logs in GitHub Actions

2. Identify the failing step (lint, test, or build)

3. Fix locally:

   bun run lint   # Check for issues
   bun run test   # Run tests
   bun run build  # Verify build

4. Push fixes to the PR branch

5. Re-run CI by pushing new commits

Common failures:

4.4 Live Tests CI

Live Tests Workflow (.github/workflows/live-tests.yml):

Triggers:

• Scheduled: Daily at 09:00 UTC
• Manual: workflow_dispatch with optional chapter tests

Environment:

RUN_LIVE_TESTS=true bun run test:live

Failure handling:

• Creates automatic issue with [AUDIBLE API CHANGE] or [AUDIBLE HTML CHANGE] label
• Requires human review and code updates

4.5 Deployment Workflows

See .github/workflows/ for deployment workflows (deploy-coolify.yml, docker-publish.yml).

5. Commit Standards

5.1 Conventional Commit Format

All commits must follow the Conventional Commits specification:

<type>(<scope>): <description>

Types:

• api - API-related changes
• db - Database-related changes
• auth - Authentication changes
• scraper - Web scraping changes
• helper - Helper function changes
• config - Configuration changes Invalid: missing type, non-conventional format, or vague description.

5.2 CI Validation

The repository uses webiny/action-conventional-commits to validate commit messages on PRs to main.

Enforcement:

• All PRs to main must have conventional commit messages
• PRs with invalid commit messages will fail the Conventional Commits check

6. Live Test Standards

6.1 When to Run Live Tests

Environment variable required:

RUN_LIVE_TESTS=true bun run test:live

Live tests are located in: tests/live/

Use cases:

• Testing against real Audible API responses
• Detecting changes in Audible's HTML structure
• Verifying API endpoint changes
• Integration testing with real data

6.3 Warning vs Failure Interpretation

Warnings (non-blocking):

[AUDIBLE API CHANGE] - Minor structure change detected
[AUDIBLE HTML CHANGE] - HTML parsing warning

Warnings indicate potential issues that should be reviewed but don't fail the build.

Failures (blocking):

[AUDIBLE API CHANGE] - Breaking API change detected
[AUDIBLE HTML CHANGE] - Critical HTML structure change

Failures indicate breaking changes that require immediate attention and code updates.

6.4 Handling Audible Changes

When live tests detect changes:

1. Review the test output for specific change details

2. Identify the affected helper in src/helpers/audible/

3. Update the helper to handle the new structure

4. Update tests in tests/audible/ if needed

5. Re-run live tests to confirm fixes

6. Commit changes with appropriate message:

   fix(audible): update book scraper for new HTML structure

Quick Reference Commands

# Development
bun install           # Install dependencies
bun run watch         # Watch mode for development
bun run debug         # Build and watch with debug

# Testing
bun run test          # Run unit tests with coverage
bun run test:live     # Run live integration tests

# Quality
bun run lint          # Check linting and formatting
bun run format        # Format code with Prettier
bun run build         # Build TypeScript

# Documentation
bun run build-docs    # Build API documentation

# Release
# Releases are handled by the annalist GitHub App with fill_after mode on main branch

File References

Last updated: 2026-02-19 Maintained by: Repository maintainers