145 lines
4.3 KiB
Markdown
145 lines
4.3 KiB
Markdown
# @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/)
|