AGENTS.md · diff

git:20260926.81c3a8f to git:20261011.f2b0439

51 added, 128 removed. Audit A to A.

# AGENTS.md

This file provides guidance to AI coding agents (Claude Code and others) when

working with code in this repository.

## Overview

`jsonr` is a CLI tool for interacting with JSON HTTP APIs and writing simple

- smoke tests. It's built with Deno and JavaScript, using JSDoc type annotations

- for type checking without TypeScript compilation.

+ smoke tests. It's written in Rust and distributed as a single binary. Keep the

+ dependency list minimal: the only crates are `ureq` (HTTP) and `rquickjs`

+ (JavaScript engine for `jsonr run`). JSON handling, argument parsing, colors

+ and value formatting are implemented in the crate itself.

## Development Commands

- ### Running the tool locally

- ```bash

- deno task run [args]

- ```

- This runs `main.js` with all permissions and ignores certificate errors for

- testing.

- ### Code quality checks

- ```bash

- deno task check

- ```

- This is the primary pre-commit verification command that runs:

- - `deno fmt --check` - Check code formatting

- - `deno lint` - Lint the codebase

- - `deno check main.js` - Type check main entry point

- - `deno check test/test.js` - Type check test entry point

- - Test suite in the `test/` directory

- ### Formatting and linting

- ```bash

- deno fmt # Format all code

- deno fmt --check # Check formatting without changes

- deno lint # Lint the codebase

- ```

- ### Type checking

- ```bash

- deno check main.js # Check main entry point

- deno check test/test.js # Check test entry point

- ```

- ### Testing

+ Development tasks are cargo aliases defined in `.cargo/config.toml` (backed by

+ the `xtask` crate):

```bash

- cd test && deno task test # Run all tests

- cd test && deno task update-snapshots # Update test snapshots

- cd test && deno task api # Run the test API server

+ cargo jsonr [args] # Run jsonr from source

+ cargo verify # fmt --check, clippy -D warnings and all tests

+ cargo test # Run all tests

+ cargo update-snapshots # Accept new CLI output in tests/snapshots

+ cargo api # Start the test API server on port 3000

```

- To run a single test, modify `test/test.js` to focus on specific test cases.

+ `cargo verify` is the pre-commit check and is what CI runs.

## Architecture

### Entry Point and Command System

- The application uses a command pattern architecture (`main.js:12-45`):

- 1. **Args parsing** (`src/args.js`) - Uses `deno_std/cli/parseArgs` to parse CLI

- arguments, normalizes kebab-case to camelCase, and handles special key-value

- arguments (`-i`, `-h`) by converting them to objects

- 2. **Config loading** (`src/config.js`) - Searches for `jsonr-config.json` files

- from home directory down to current directory, merges them hierarchically,

- and applies environment-specific configuration

- 3. **Command matching** - Each command exports a `match(args)` function to

- determine if it should handle the request

- 4. **Command execution** - The first matching command's `execute(args)` function

- is called

- ### Commands

- All commands are in `src/commands/`:

- - `send-request.js` - Core functionality for sending HTTP requests (handles both

- .http files and direct URLs)

- - `run.js` - Executes JavaScript files with jsonr API available, or generates

- example scripts

- - `config.js` - Manages jsonr-config.json files

- - `help.js` - Displays help text

- - `version.js` - Shows version information

- - `update.js` - Updates the tool to latest version

- ### Configuration System

- The config system (`src/config.js`) has several key features:

- 1. **Hierarchical loading** - Searches from `$HOME` to current directory for

- `jsonr-config.json` files and merges them (closer to current directory wins)

- 2. **Environment support** - Config files can define named environments with

- different input variables, headers, and secrets

- 3. **Secrets management** - Supports separate JSON files for secrets (referenced

- via `secrets` field), which are automatically masked in debug logs

- 4. **JSON comment support** - Strips `//` and `#` comments from JSON files and

- removes trailing commas before parsing

- ### Request Processing

- HTTP request handling (`src/commands/send-request.js`):

- 1. **Input sources**:

- - `.http` files (VSCode REST Client format)

- - Direct URL with options (`-m`, `-b`, `-h` flags)

- 2. **Variable substitution** - `@@variableName@@` placeholders are replaced with

- values from:

- - Command-line input variables (`-i`)

- - Config file input variables

- - Secrets files

- 3. **.http file format**:

- ```

- METHOD URL

- Header: value

- body content

- ```

- 4. **Response handling**:

- - Status code assertions (`-s` flag)

- - Text content assertions (`-t` flag)

- - Output to file (`-o` flag)

- - Raw mode (`-r` flag) - shows response without formatting

+ `src/main.rs`:

- ### Programmatic API

+ 1. **Args parsing** (`src/args.rs`) - Port of `@std/cli` `parseArgs` used by the

+ Deno version: unknown flags are accepted, aliases are stored under both

+ names, kebab-case is normalized to camelCase and `-i`/`-h` values become

+ objects. Arguments are a dynamic `json::Object` because config files can set

+ any option.

+ 2. **Config loading** (`src/config.rs`) - Searches for `jsonr-config.json` files

+ from the current directory up to the home directory, merges them (closer to

+ the current directory wins) and applies the environment selected with `-e`.

+ 3. **Command dispatch** - help, version, update, run, config, skill, otherwise

+ a request is sent (`src/request.rs`).

- The `run` command (`src/commands/run.js`) enables JavaScript scripting:

+ Errors returned by commands are logged and jsonr exits with code 1, as do

+ failed assertions (`-s`, `-t`), missing files and missing variables.

- - Exposes a global `jsonr()` function when executing scripts via

- `jsonr run script.js`

- - The function accepts same arguments as CLI but in object form

- - Allows chaining requests and programmatic response handling

- - Can generate starter templates with `jsonr run --init`

+ ### Modules

- ## Type Checking

+ - `src/request.rs` - Builds the request (URL, `.http` file or stdin), sends it

+ with `ureq`, prints the response and runs assertions

+ - `src/http_file.rs` - `.http` parsing, `@@var@@`/`{{var}}` substitution and

+ the `--js` body conversion

+ - `src/script.rs` + `src/script_prelude.js` - `jsonr run`: executes scripts in

+ QuickJS with a global `jsonr()`, `console` and `Headers`

+ - `src/inspect.rs` - Value formatting identical to `Deno.inspect` (port of

+ Deno's console formatter)

+ - `src/json.rs` - JSON parse/stringify with JavaScript semantics

+ - `src/update.rs` - `jsonr update` (self-update from GitHub releases) and the

+ daily check for new versions

+ - `src/commands/` - help, run, config and skill commands

+ - `src/help.txt`, `src/templates/` - help text and generated file templates

- The project uses JavaScript with JSDoc type annotations:

+ ## Testing

- - `main.js` has types defined in `main.d.ts` via `@ts-self-types` directive

- - TypeScript checking is enabled via `deno.json` `compilerOptions.checkJs: true`

- - Some strict checks are disabled (`noImplicitAny`, `strictNullChecks`,

- `useUnknownInCatchVariables`)

+ - Unit tests live next to the code (`#[cfg(test)]`).

+ - `tests/cli.rs` runs the compiled binary against a std-only test API

+ (`tests/support/test_api.rs`, port 3000) and compares output with

+ `tests/snapshots/*.snap`. Fixtures are in `tests/fixtures/`.

+ - `tests/fixtures/inspect-cases.json` holds `Deno.inspect` reference output

+ that `src/inspect.rs` must reproduce.

## Logging

- `src/logger.js` provides debug logging:

+ `src/logger.rs`:

- Debug logs only appear when `--debug` flag is used

- Secrets from secrets files are automatically masked in logs

- Color output can be disabled with `NO_COLOR=1` environment variable

## Landing Page

The landing page lives in `docs/index.html`. Every time you introduce a new

feature or change existing behavior, update the landing page as well, so it

always reflects the current feature set.

## Publishing

- The package is published to JSR as `@sobanieca/jsonr`. Precompiled binaries are

- built for multiple platforms (Linux/macOS, x64/arm64) and distributed via GitHub

- releases.

+ Every push to `main` builds binaries for Linux (musl, static) and macOS

+ (x64/arm64) and publishes them as GitHub release `v<version>` (version from

+ `Cargo.toml`). `install.sh` and `jsonr update` download these release assets,

+ so their names (`jsonr-linux-x64`, ...) must not change.