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

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

License

CC BY-ND 4.0