@byteb4rb1e/mime-todo

CLI implementation for the MIME TODO specification

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

Install

npm install -g @byteb4rb1e/mime-todo

Quick Start

# 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.

mime-todo init                                          # check what exists
mime-todo init --dry-run                                # preview changes
mime-todo init --confirm --assignee [email protected]    # 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.

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:

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 [email protected]

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. The specification defines the file format, field semantics, status transition rules, and commit conventions.

License

CC BY-ND 4.0