chore: polish for publishing

2026-03-15 03:20:59 +01:00 · 2026-03-15 03:20:59 +01:00 · e4db005b04
commit e4db005b04
parent bac4a87119
3 changed files with 207 additions and 18 deletions
--- a/25
+++ b/25
@ -0,0 +1,25 @@
+Creative Commons Attribution-NoDerivatives 4.0 International
+
+Copyright (c) 2026 Tiara Rodney
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format
+  for any purpose, even commercially.
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to
+  the license, and indicate if changes were made. You may do so in
+  any reasonable manner, but not in any way that suggests the licensor
+  endorses you or your use.
+
+  NoDerivatives — If you remix, transform, or build upon the material,
+  you may not distribute the modified material.
+
+  No additional restrictions — You may not apply legal terms or
+  technological measures that legally restrict others from doing
+  anything the license permits.
+
+Full license text:
+https://creativecommons.org/licenses/by-nd/4.0/legalcode
--- a/README.md
+++ b/README.md
@ -0,0 +1,144 @@
+# @byteb4rb1e/mime-todo
+
+CLI 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
+todo create --type feature --title "Add login" --plan "Implement OAuth2 flow"
+todo start 1 --plan "Using passport.js with Google provider"
+todo push          # sync to Bugzilla
+todo done 1 --summary "OAuth2 login with Google, GitHub providers"
+```
+
+## Commands
+
+### Issue Lifecycle
+
+| Command | Branch | Description |
+|---------|--------|-------------|
+| `todo create --type --title --plan` | `develop` | Create a new issue |
+| `todo start <id> --plan` | `develop` | Set issue to in-progress |
+| `todo done <id> --summary` | `<type>/<id>` | Mark issue as done |
+| `todo hold <id> --reason` | `<type>/<id>` | Put issue on hold |
+| `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 |
+|---------|-------------|
+| `todo list` | List all issues |
+| `todo show <id>` | Show issue details |
+| `todo sprints` | List all sprints |
+| `todo issues-in-sprint <name>` | List issues in a sprint |
+
+### Bugzilla Integration
+
+| Command | Description |
+|---------|-------------|
+| `todo init` | Check/create Bugzilla products and components |
+| `todo push [ref]` | Push commits as Bugzilla comments |
+
+#### `todo init`
+
+Reads the `application/bugzilla` part from the `TODO` file and ensures the
+referenced products and components exist on the Bugzilla server.
+
+```sh
+todo init                                          # check what exists
+todo init --dry-run                                # preview changes
+todo init --confirm --assignee user@example.com    # create missing items
+```
+
+#### `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
+todo push              # push all unpushed commits
+todo push HEAD~3       # push only the last 3 commits
+todo push --dry-run    # preview without pushing
+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/)
--- a/package.json
+++ b/package.json
@ -1,10 +1,41 @@
 {
-  "name": "byteb4rb1e/mime-todo",
-  "version": "1.0.0",
-  "author": "",
-  "license": "ISC",
-  "description": "MIME TODO issue tracker with Bugzilla sync",
+  "name": "@byteb4rb1e/mime-todo",
+  "version": "0.1.0",
+  "description": "CLI for the MIME TODO issue tracker specification with Bugzilla integration",
+  "author": "Tiara Rodney <me@tiararodney.com>",
+  "license": "CC-BY-ND-4.0",
  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@bitbucket.org/byteb4rb1e/mime-todo-cli.git"
+  },
+  "homepage": "https://bitbucket.org/byteb4rb1e/mime-todo-cli",
+  "bugs": {
+    "url": "https://bugs.code.tiararodney.com/buglist.cgi?component=CLI&product=MIME%20TODO"
+  },
+  "keywords": [
+    "todo",
+    "issue-tracker",
+    "mime",
+    "bugzilla",
+    "cli",
+    "gitflow"
+  ],
+  "bin": {
+    "todo": "./bin/main.ts",
+    "bugzilla": "./bin/bugzilla.ts"
+  },
+  "main": "lib/file.ts",
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "todo": "tsx bin/main.ts",
+    "bugzilla": "tsx bin/bugzilla.ts",
+    "test": "vitest run"
+  },
  "dependencies": {
    "ajv": "^8.17.1",
    "mailparser": "^3.9.3",
@ -15,18 +46,7 @@
    "@types/yargs": "^17.0.35",
    "vitest": "^4.0.18"
  },
-  "bin": {
-    "todo": "./bin/main.ts",
-    "bugzilla": "./bin/bugzilla.ts"
-  },
-  "scripts": {
-    "todo": "tsx bin/main.ts",
-    "bugzilla": "tsx bin/bugzilla.ts",
-    "test": "vitest run"
-  },
-  "main": "dist/main.js",
-  "directories": {
-    "lib": "lib",
-    "test": "tests"
+  "engines": {
+    "node": ">=18.0.0"
  }
 }