moth-cli 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +39 -113
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,177 +1,103 @@
1
1
  # moth
2
2
 
3
- An opinionated issue tracker that lives in your repository. Tickets are markdown files with an enforced schema — no account, no server, no sign-up.
3
+ [![ci](https://github.com/nikolasgioannou/moth/actions/workflows/ci.yml/badge.svg)](https://github.com/nikolasgioannou/moth/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/moth-cli)](https://www.npmjs.com/package/moth-cli) [![license](https://img.shields.io/github/license/nikolasgioannou/moth)](LICENSE)
4
4
 
5
- Built for coding agents and the people who use them.
5
+ An issue tracker that lives in your repository. Tickets are markdown files with a schema the CLI enforces — no account, no server, no sign-up.
6
6
 
7
7
  ```
8
8
  $ moth list
9
9
  backlog
10
- 003 Ship the first binary high
11
- 002 Handle quoted strings none ↳ 001
12
-
13
- in-progress
14
- 001 Parse the frontmatter none
10
+ 280f4d Ship the binary high
11
+ 8e0642 Parse the frontmatter none
15
12
  ```
16
13
 
17
- ## Why it exists
18
-
19
- A folder of markdown files is free, but it is a convention rather than a tool, and nothing enforces it. Session one's agent writes `status: todo`. Session three's agent, having never seen that file, writes `state: in_progress`. By session ten the folder is unqueryable, and answering "what's blocked?" means re-deriving a grep every time.
20
-
21
- moth's value is the constraint. It refuses writes a bare filesystem would accept: an unrecognised status, a field nobody declared, a parent that would create a cycle. An agent cannot invent `status: blocked` on a whim, because the write fails and tells it what is legal. And it can ask: `moth schema --json` returns every legal field and value for the repository, so a session with no memory of previous sessions can discover the rules in one call.
22
-
23
- Because the shape of the data is known, querying it is a command rather than a grep somebody has to get right.
24
-
25
- ## What it deliberately does not do
26
-
27
- The refusals are the design, not gaps waiting to be filled:
28
-
29
- - **No assignees, and no accounts.** Moving a ticket into a started status is how you claim it.
30
- - **No custom statuses outside six fixed categories.** You name your own statuses; every one belongs to `backlog`, `unstarted`, `started`, `completed`, `canceled`, or `duplicate`. Queries against categories work in any repository; queries against your status names work in yours.
31
- - **No undeclared fields.** Custom fields are allowed, but they must be declared in config first, so an agent can never introduce one.
32
- - **No comments and no activity log.** `git log -p` on a ticket file is already a complete, attributed, tamper-evident history. Notes append to the body.
33
- - **No cycles, sprints, estimates, projects, or manual ordering.**
34
- - **No web UI, and no TUI.** The CLI is the interface.
35
-
36
- The full list, each with its reasoning, is in [the spec](docs/spec-v1.md#out-of-scope).
37
-
38
- ## Installing
39
-
40
- ### Homebrew
14
+ ## Install
41
15
 
42
16
  ```sh
43
17
  brew install nikolasgioannou/tap/moth
44
18
  ```
45
19
 
46
- ### Shell
47
-
48
20
  ```sh
49
21
  curl -fsSL https://raw.githubusercontent.com/nikolasgioannou/moth/main/install.sh | sh
50
22
  ```
51
23
 
52
- Installs to `~/.local/bin` by default. Set `MOTH_INSTALL_DIR` to change that, or `MOTH_VERSION` to pin a release. The download is checked against the release's published checksums.
53
-
54
- ### npm
55
-
56
24
  ```sh
57
25
  npm install -g moth-cli
58
26
  ```
59
27
 
60
- Or run it without installing: `npx moth-cli list`. Only your platform's binary is downloaded, not all five.
28
+ Or grab a binary from [releases](https://github.com/nikolasgioannou/moth/releases). macOS, Linux and Windows.
61
29
 
62
- ### From a release
63
-
64
- Binaries for macOS, Linux and Windows are attached to every [release](https://github.com/nikolasgioannou/moth/releases), alongside a `SHA256SUMS` file. Download one, `chmod +x` it, and put it on your `PATH`.
65
-
66
- ### From source
30
+ ## Use it
67
31
 
68
32
  ```sh
69
- git clone https://github.com/nikolasgioannou/moth.git
70
- cd moth
71
- bun install
72
- bun run build
33
+ moth init # one question per status, Enter accepts each
34
+ moth new "Parse the frontmatter" # prints the id it assigned
35
+ moth new "Ship the binary" --body "Needs the parser first."
36
+ moth edit 280f4d --blocked-by 8e0642 --priority high --label release
73
37
  ```
74
38
 
75
- ## A worked example
39
+ Then ask what you can actually start, rather than what merely exists:
76
40
 
77
- Starting from a repository with no tickets:
78
-
79
- ```sh
80
- $ moth init
81
- Statuses in 'backlog' [backlog]
82
- Statuses in 'unstarted' [todo]
83
- Statuses in 'started' [in-progress]
84
- Statuses in 'completed' [done]
85
- Statuses in 'canceled' [canceled]
86
- Statuses in 'duplicate' [duplicate]
87
41
  ```
88
-
89
- One question per status category, and Enter accepts each default. That writes `moth.config.yml` at the root and creates `.moth/` for the tickets. Then file some work:
90
-
91
- ```sh
92
- $ moth new "Parse the frontmatter"
93
- 001 Parse the frontmatter
94
-
95
- $ moth new "Handle quoted strings" --parent 1
96
- 002 Handle quoted strings
97
-
98
- $ moth new "Ship the first binary" --body "Blocked on the parser landing."
99
- 003 Ship the first binary
42
+ $ moth list --unblocked
43
+ backlog
44
+ 8e0642 Parse the frontmatter none
100
45
  ```
101
46
 
102
- Relate and prioritise it:
47
+ `280f4d` is missing because it is waiting on `8e0642`.
103
48
 
104
- ```sh
105
- $ moth edit 3 --blocked-by 1 --priority high --label release
106
- 003 Ship the first binary
49
+ Name a ticket however you remember it. `moth show 280f4d`, `moth show 280` and `moth show "ship the binary"` all find the same one, and an ambiguous reference lists the candidates rather than guessing.
107
50
 
108
- $ moth move 1 in-progress
109
- 001 Parse the frontmatter in-progress
110
- ```
51
+ `moth --help` lists every command; each one's `--help` carries a worked example. `moth schema --json` reports exactly what this repository considers a legal ticket, which is how an agent learns the rules in one call.
111
52
 
112
- Then ask what is actually startable — work that has been committed to and is not waiting on anything:
53
+ ## Why it exists
113
54
 
114
- ```sh
115
- $ moth list --unblocked --category backlog
116
- backlog
117
- 002 Handle quoted strings none ↳ 001
118
- ```
55
+ A folder of markdown files is free, but nothing enforces it. Session one's agent writes `status: todo`. Session three's agent, having never seen that file, writes `state: in_progress`. By session ten the folder is unqueryable, and "what's blocked?" means re-deriving a grep every time.
119
56
 
120
- And look at one ticket:
57
+ moth refuses writes a bare filesystem would accept: an unrecognised status, a field nobody declared, a parent that would form a cycle. An agent cannot invent `status: blocked`, because the write fails and says what is legal. Because the shape is known, querying it is a command rather than a grep somebody has to get right.
121
58
 
122
- ```sh
123
- $ moth show 3
124
- 003 Ship the first binary
125
- status backlog
126
- priority high
127
- labels release
128
- blocked by 001
129
- created 2026-08-31T00:35:11.462Z
130
- updated 2026-08-31T00:35:11.484Z
59
+ ## What it refuses to do
131
60
 
132
- Blocked on the parser landing.
133
- ```
61
+ The refusals are the design, not gaps:
134
62
 
135
- A ticket is referred to by its number, padded or not, or by words from its title: `moth show 3`, `moth show 003`, and `moth show "quoted strings"` all work. An ambiguous reference lists the candidates rather than guessing.
63
+ - **No assignees, no accounts.** Moving a ticket into a started status is how you claim it.
64
+ - **No statuses outside six fixed categories.** Name your own; each belongs to `backlog`, `unstarted`, `started`, `completed`, `canceled` or `duplicate`. Queries by category work in any repository.
65
+ - **No undeclared fields.** Custom fields are allowed, but must be declared in config first, so an agent can never introduce one.
66
+ - **No comments, no activity log.** `git log -p` on a ticket is already a complete, attributed history.
67
+ - **No cycles, sprints, estimates, projects or manual ordering. No web UI, no TUI.**
136
68
 
137
- ## How it is stored
69
+ Every rejection, with its reasoning, is in [the spec](docs/spec-v1.md#out-of-scope).
138
70
 
139
- ```
140
- moth.config.yml statuses, custom fields, where tickets live
141
- .moth/
142
- 001-parse-the-frontmatter.md
143
- 002-handle-quoted-strings.md
144
- ```
71
+ ## Storage
145
72
 
146
- One markdown file per ticket, flat, with YAML frontmatter for structured fields and the body for the description. Nothing central that every write touches, so two branches creating tickets merge without conflict. Commit them with your code and they travel through branches, clones and pull requests.
73
+ `moth.config.yml` at the root, and one markdown file per ticket in `.moth/`:
147
74
 
148
75
  ```markdown
149
76
  ---
150
- id: 3
77
+ id: "280f4d"
151
78
  title: Ship the first binary
152
79
  status: backlog
153
80
  priority: high
154
81
  labels:
155
82
  - release
156
- created_at: 2026-08-31T00:35:11.462Z
157
- updated_at: 2026-08-31T00:35:11.484Z
83
+ created_at: 2026-08-31T02:31:59.759Z
84
+ updated_at: 2026-08-31T02:31:59.787Z
158
85
  blocked_by:
159
- - 1
86
+ - "8e0642"
160
87
  ---
161
88
 
162
89
  Blocked on the parser landing.
163
90
  ```
164
91
 
165
- ## Commands
166
-
167
- Run `moth --help` for the list, and `moth <command> --help` for a worked example of any one of them. `moth schema --json` reports what this repository considers a legal ticket.
92
+ Flat, with nothing central that every write touches, so two branches creating tickets merge cleanly. Commit them with your code and they travel through branches, clones and pull requests.
168
93
 
169
- ## Design notes
94
+ ## Design
170
95
 
171
96
  - [The v1 spec](docs/spec-v1.md) — what was built, and every rejected alternative
172
97
  - [Architecture decisions](docs/adr/) — including two reversals, with the reasoning that changed
98
+ - [Contributing](CONTRIBUTING.md)
173
99
 
174
- moth tracks its own development in moth: the backlog is in [`.moth/`](.moth/).
100
+ moth tracks its own development in moth: the backlog is [`.moth/`](.moth/).
175
101
 
176
102
  ## Licence
177
103
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "moth-cli",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "An opinionated issue tracker that lives in your repo. Tickets are markdown files with an enforced schema.",
5
5
  "keywords": [
6
6
  "issue-tracker",
@@ -22,10 +22,10 @@
22
22
  "bin"
23
23
  ],
24
24
  "optionalDependencies": {
25
- "moth-cli-darwin-arm64": "0.1.0",
26
- "moth-cli-darwin-x64": "0.1.0",
27
- "moth-cli-linux-arm64": "0.1.0",
28
- "moth-cli-linux-x64": "0.1.0",
29
- "moth-cli-windows-x64": "0.1.0"
25
+ "moth-cli-darwin-arm64": "0.2.0",
26
+ "moth-cli-darwin-x64": "0.2.0",
27
+ "moth-cli-linux-arm64": "0.2.0",
28
+ "moth-cli-linux-x64": "0.2.0",
29
+ "moth-cli-windows-x64": "0.2.0"
30
30
  }
31
31
  }