# nbd

A CLI tool for managing work tickets, primarily targeted at agent workflows.

Tickets are stored as JSON files in `.nbd/tickets/` inside the nearest ancestor
directory that contains a `.nbd/` folder, discovered by traversing upward from
the current working directory — just like `git` finds `.git/`.

## How it works

Each ticket is a JSON file named `{id}.json`, where `id` is a unique
6-character lowercase hex string (e.g. `a3f9c2`). Tickets carry:

| Field | Type | Default |
|---|---|---|
| `id` | 6-char hex string | auto-generated |
| `title` | string | *(required)* |
| `body` | string | `""` |
| `priority` | integer 0–10 | `5` |
| `status` | `todo` \| `in_progress` \| `done` \| `closed` | `todo` |
| `ticket_type` | `project` \| `feature` \| `task` \| `bug` | `task` |
| `dependencies` | list of ticket IDs | `[]` |

All commands accept `--json` for machine-readable output.

## Usage

### Initialise

Create the ticket store in your project root:

```sh
nbd init
```

Analogous to `git init` — safe to run multiple times.

### Create a ticket

```sh
nbd create --title "Fix login bug" --priority 8 --type bug
nbd create --title "Add rate limiting" --body "Protect public endpoints" --deps a3f9c2
```

### Read a ticket

```sh
nbd read a3f9c2
nbd read a3f9c2 --json
```

### List all tickets

By default, `done` and `closed` tickets are excluded.

```sh
nbd list                          # todo + in_progress only (done + closed excluded)
nbd list --all                    # all tickets including done and closed
nbd list --filter status=*        # all tickets (alias for --all via filter)
nbd list --filter status=done     # only completed tickets
nbd list --filter status=closed   # only archived tickets
nbd list --filter type=bug        # non-done, non-closed bug tickets
nbd list --json
```

### Archive a ticket

Soft-delete a ticket by setting its status to `closed`. The file is preserved
on disk but hidden from normal listings.

```sh
nbd archive a3f9c2
nbd archive a3f9c2 --json
```

`nbd archive` is shorthand for `nbd update <id> --status closed`. Archived
tickets still count as resolved for dependency purposes — any ticket that
depends on an archived ticket becomes unblocked.

### Update a ticket

Only the flags you supply are changed; all other fields retain their current
values.

```sh
nbd update a3f9c2 --status in_progress
nbd update a3f9c2 --priority 9 --type bug
```

### Find the next ticket to work on

Returns the single highest-priority ticket that is ready to work on — not done
and with all dependencies completed:

```sh
nbd next
nbd next --json
nbd next --filter type=bug     # highest-priority ready bug
nbd next --filter priority=9   # highest-priority ready ticket at priority 9
```

Exits 0 even when no ready ticket exists (`{"next": null}` in JSON mode).

### Find all actionable tickets

List all tickets that are ready to work on — not done and with all dependencies
completed:

```sh
nbd ready
nbd ready --json
```

### Migrate ticket files

Re-serialise all ticket files through the current schema. Use this after
upgrading `nbd` to remove stale fields, add new fields with defaults, and
normalise formatting.

```sh
nbd migrate
nbd migrate --dry-run   # preview changes without writing
nbd migrate --json      # machine-readable summary
```

## Running

```sh
# From the nbd/ directory
cargo run -- init
cargo run -- create --title "Test ticket" --priority 7 --type bug
cargo run -- list
cargo run -- list --all
cargo run -- ready
cargo run -- read <id>
cargo run -- update <id> --status in_progress
cargo run -- archive <id>
cargo run -- list --json
```

## Testing

```sh
cargo test
```

Unit tests live in `src/tests.rs`. Integration tests (full command flows against
a temporary directory) live in `tests/integration.rs`.

## Development

Run these commands in order before committing:

```sh
cargo fmt
cargo check
cargo clippy
cargo test
```

## License

Dual-licensed under [Apache License, Version 2.0](../LICENSE-APACHE) and
[MIT License](../LICENSE-MIT), consistent with the rest of the `vibed` mono-repo.

---

*This software was written with [Claude Code](https://claude.com/claude-code)
using the claude-sonnet-4-6 model.*