skillbox: Instructions file for Codex

Skillbox Agent Guide

This file is for agentic coding tools operating in this repo. Keep output deterministic, prefer JSON modes, and follow existing conventions.

Build, Lint, Format, Test

This project uses the Oxc suite for linting and formatting.

Install

npm install

Build

npm run build

Lint

npm run lint
npm run lint:fix
npm run lint:ci

Format

npm run format
npm run format:check

Tests

npm test           # Run all tests
npm run test:watch # Watch mode
npm run test:ci    # CI mode with JUnit output

Run a single test file:

npx vitest run tests/integration/add.test.ts

Run tests matching a pattern:

npx vitest run -t "config"

Code Style Guidelines

Language and Runtime

• TypeScript, ES modules, Node.js.
• Use async/await for I/O; avoid synchronous filesystem calls.

Imports

• Use named imports and explicit module paths.
• Group imports: built-ins, external deps, local modules.
• Keep type-only imports with import type.

Formatting

• Use oxfmt via npm run format.
• Target print width is 100.
• Use double quotes in TypeScript files (oxfmt default).

Types

• Prefer explicit return types on exported functions.
• Avoid any; use narrow unions and helper types.
• Use type for aliases; use interface only when extending public shapes.

Naming

• Files: kebab-case for new modules under src/lib or src/commands.
• Functions: verb-first (loadConfig, resolveRuntime).
• Constants: camelCase for values, UPPER_SNAKE only for compile-time constants.

Error Handling

• Use handleCommandError for CLI command errors.
• Return JSON errors when --json is set.
• Throw Error with clear, user-facing messages.

CLI Patterns

• Commands should support --json output.
• Use shared helpers: handleCommandError, printList, printGroupList, grouping utilities.
• Keep output stable and concise for agent usage.