# @byteb4rb1e/mime-todo

CLI implementation for the [MIME TODO specification](https://bitbucket.org/byteb4rb1e/mime-todo-spec) 

A deterministic, spec-first issue tracker that lives inside a SCM repository as
a plain-text `TODO` file.

## Install

```sh
npm install -g @byteb4rb1e/mime-todo
```

## Quick Start

```sh
# Create a TODO file and start tracking issues
mime-todo create --type feature --title "Add login" --plan "Implement OAuth2 flow"
mime-todo start 1 --plan "Using passport.js with Google provider"
mime-todo push          # sync to Bugzilla
mime-todo done 1 --summary "OAuth2 login with Google, GitHub providers"
```

## Commands

### Issue Lifecycle

| Command | Branch | Description |
|---------|--------|-------------|
| `mime-todo create --type --title --plan` | `develop` | Create a new issue |
| `mime-todo start <id> --plan` | `develop` | Set issue to in-progress |
| `mime-todo done <id> --summary` | `<type>/<id>` | Mark issue as done |
| `mime-todo hold <id> --reason` | `<type>/<id>` | Put issue on hold |
| `mime-todo cancel <id> --reason` | `develop` or `<type>/<id>` | Cancel an issue |

Each lifecycle command creates a dedicated commit (`todo(<id>): <status>`)
that modifies only the `TODO` file.

### Read-Only

| Command | Description |
|---------|-------------|
| `mime-todo list` | List all issues |
| `mime-todo show <id>` | Show issue details |
| `mime-todo sprints` | List all sprints |
| `mime-todo issues-in-sprint <name>` | List issues in a sprint |

### Bugzilla Integration

| Command | Description |
|---------|-------------|
| `mime-todo init` | Check/create Bugzilla products and components |
| `mime-todo push [ref]` | Push commits as Bugzilla comments |

#### `mime-todo init`

Reads the `application/bugzilla` part from the `TODO` file and ensures the
referenced products and components exist on the Bugzilla server.

```sh
mime-todo init                                          # check what exists
mime-todo init --dry-run                                # preview changes
mime-todo init --confirm --assignee user@example.com    # create missing items
```

#### `mime-todo push`

Pushes git commits to Bugzilla as comments. Context-aware:

- **On issue branches**: pushes work commits as comments on the
  corresponding bug (work log).
- **On `develop`**: pushes `todo(<id>): <status>` transition commits,
  updating bug status and posting the commit body as a comment.

```sh
mime-todo push              # push all unpushed commits
mime-todo push HEAD~3       # push only the last 3 commits
mime-todo push --dry-run    # preview without pushing
mime-todo push --strategy full   # re-scan all bugs (not just targeted)
```

Each comment includes a clickable link to the commit. Comments are tagged
with `git-<short-hash>` for idempotency — running `push` twice is safe.

### Standalone Bugzilla CLI

A separate `bugzilla` command provides direct access to the Bugzilla REST
API:

```sh
bugzilla products
bugzilla product "MIME TODO"
bugzilla components "MIME TODO"
bugzilla search --product "MIME TODO"
bugzilla get <id>
bugzilla create --summary "Bug title" --description "Details"
bugzilla create-product --name "Product" --description "Desc"
bugzilla create-component --product "Product" --name "Comp" \
  --description "Desc" --assignee user@example.com
```

## Configuration

### Environment Variables

| Variable | Description |
|----------|-------------|
| `BUGZILLA_URL` | Bugzilla REST API URL (e.g. `https://bugs.example.com/rest`) |
| `BUGZILLA_API_KEY` | Bugzilla API key |

### TODO File

The `TODO` file can contain `application/modules` and `application/bugzilla`
parts to configure module-to-product/component mappings:

```
--ISSUE
Content-Type: application/modules
Modules:
        - Name: Specification
          Path: src
        - Name: CLI
          Path: scripts/cli

--ISSUE
Content-Type: application/bugzilla
URL: https://bugs.example.com/rest
Mappings:
        - Module: Specification
          Product: MIME TODO
          Component: Specification
        - Module: CLI
          Product: MIME TODO
          Component: CLI
```

## Specification

This CLI implements the [MIME TODO specification](https://bitbucket.org/byteb4rb1e/mime-todo-spec).
The specification defines the file format, field semantics, status transition
rules, and commit conventions.

## License

[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/)