open-backlog 0.0.0-stage → 0.1.1

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Brandon Castagna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,310 @@
1
- # Temporary Holding Version
1
+ # Open Backlog
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `ob` keeps your backlog as Markdown files in git, next to your code. Every epic, feature and
4
+ story is a file. A story's folder (`todo/`, `doing/`, `done/`) is its status, and git history is
5
+ its timeline. You need no server and no account, and any editor, script or AI agent can read it.
6
+
7
+ This package, `open-backlog`, is the `ob` command and the library it is built on. It follows the
8
+ [Open Backlog spec](https://openbacklog.org/spec) **version 0.1**.
9
+
10
+ ## Install
11
+
12
+ You need Node.js 22 or later, and git.
13
+
14
+ ```sh
15
+ npm i -g open-backlog
16
+ ob --version
17
+ ```
18
+
19
+ To run it once without installing: `npx -p open-backlog ob <command>`.
20
+
21
+ ## A five-minute start
22
+
23
+ In a git repository, create the backlog and commit it:
24
+
25
+ ```sh
26
+ $ ob init --name shop
27
+ Created the shop backlog in backlog/:
28
+ config.yml
29
+ epics/.gitkeep
30
+ features/.gitkeep
31
+ stories/todo/.gitkeep
32
+ stories/doing/.gitkeep
33
+ stories/done/.gitkeep
34
+ Next: git add backlog && git commit -m "ob: init shop backlog"
35
+ $ git add backlog && git commit -m "ob: init shop backlog"
36
+ ```
37
+
38
+ Add an epic, a feature under it and two stories. Each `ob new` takes the next free number and
39
+ commits only that file:
40
+
41
+ ```sh
42
+ $ ob new epic "Checkout"
43
+ Created 1 backlog/epics/1-checkout.md
44
+ Committed: ob: add 1 Checkout
45
+ $ ob new feature "Pay by card" --parent 1
46
+ $ ob new story "Card form" --parent 1.1
47
+ $ ob new story "Save the card" --parent 1.1
48
+ ```
49
+
50
+ A bug or task that fits no plan needs no parent. It goes into this month's feature in epic 0,
51
+ "Unplanned work":
52
+
53
+ ```sh
54
+ $ ob new bug "Total rounds wrong"
55
+ Created 0 backlog/epics/0-unplanned.md
56
+ Created 0.1 backlog/features/0.1-2026-11.md
57
+ Created 0.1.1 backlog/stories/todo/0.1.1-total-rounds-wrong.md
58
+ Committed: ob: add 0.1.1 Total rounds wrong
59
+ ```
60
+
61
+ Start a story, finish it and look at the plan:
62
+
63
+ ```sh
64
+ $ ob start 1.1.1
65
+ Moved 1.1.1 to doing: backlog/stories/todo/1.1.1-card-form.md → backlog/stories/doing/1.1.1-card-form.md
66
+ Committed: ob: move 1.1.1 to doing
67
+ $ ob list
68
+ 0.1.1 todo Total rounds wrong
69
+ 1.1.1 doing Card form
70
+ 1.1.2 todo Save the card
71
+ $ ob done 1.1.1
72
+ $ ob tree
73
+ 0 todo 0/1 done (0%) Unplanned work
74
+ 0.1 todo 0/1 done (0%) Unplanned, 2026-11
75
+ 0.1.1 todo Total rounds wrong
76
+ 1 doing 1/2 done (50%) Checkout
77
+ 1.1 doing 1/2 done (50%) Pay by card
78
+ 1.1.1 done Card form
79
+ 1.1.2 todo Save the card
80
+ $ ob validate
81
+ backlog/ is valid, 7 items
82
+ ```
83
+
84
+ Open `backlog/stories/todo/1.1.2-save-the-card.md` in any editor to write the story. `ob show
85
+ 1.1.2` prints it with where it sits in the plan and its history. Push, and your team has the
86
+ backlog with the code.
87
+
88
+ ## What a backlog looks like
89
+
90
+ ```
91
+ backlog/
92
+ config.yml spec: 0.1, name: shop
93
+ epics/1-checkout.md
94
+ features/1.1-pay-by-card.md feature 1 of epic 1
95
+ stories/
96
+ todo/1.1.2-save-the-card.md stories, bugs, spikes and tasks
97
+ doing/
98
+ done/1.1.1-card-form.md
99
+ ```
100
+
101
+ Each file starts with front matter: `id`, `type`, `title` and `parent`, plus optional
102
+ fields such as `repo`, `assignee`, `sprint` and `estimate`. The rest is Markdown. The
103
+ [spec](https://openbacklog.org/spec) gives every field and rule.
104
+
105
+ ## Commands
106
+
107
+ Every command takes `--help`. `ob --help` lists them all.
108
+
109
+ ### ob init
110
+
111
+ ```sh
112
+ ob init [--name <name>] [--readme]
113
+ ```
114
+
115
+ This creates `backlog/` at the top of the git repository (or in the current folder, outside git).
116
+ It writes a two-line `config.yml` (`spec: 0.1`, `name: …`) and the folders `epics/`, `features/`
117
+ and `stories/todo|doing|done/`, each with a `.gitkeep`. It doesn't commit; it prints the
118
+ command to run.
119
+
120
+ - `--name <name>`: the backlog's name, made of lowercase letters, digits and dashes. It
121
+ defaults to the repository's folder name.
122
+ - `--readme`: also write `backlog/README.md`, which explains the folders.
123
+
124
+ It never overwrites a file. If `backlog/config.yml` exists, it changes nothing and says so.
125
+
126
+ ### ob new
127
+
128
+ ```sh
129
+ ob new <type> <title> [--parent <id>] [--slug <slug>] [--edit] [--no-commit]
130
+ ```
131
+
132
+ This adds a `capability`, `epic`, `feature`, `story`, `bug`, `spike` or `task`. It takes the
133
+ next number ever used under the parent, counting items removed in git history, so a number is
134
+ never reused. It writes the file from the template (stories, bugs, spikes and tasks go in
135
+ `stories/todo/`) and commits just that file: `ob: add 1.1.1 Card form`. The parent is checked
136
+ first, so a mistake writes nothing.
137
+
138
+ - `--parent <id>`: the item it's filed under. A feature needs an epic, and a story, bug, spike
139
+ or task needs a feature. An epic may have a capability. A bug or task with no parent goes into
140
+ this month's feature in epic 0, which is created if needed.
141
+ - `--slug <slug>`: the words in the file name (by default, taken from the title).
142
+ - `--edit`: open the new file in `$VISUAL` or `$EDITOR`, then commit what you save.
143
+ - `--no-commit`: write the file and leave committing to you.
144
+
145
+ ### ob move, ob start, ob done
146
+
147
+ ```sh
148
+ ob move <id> <todo|doing|done> [--no-commit]
149
+ ob start <id> [--no-commit] # ob move <id> doing
150
+ ob done <id> [--no-commit] # ob move <id> done
151
+ ```
152
+
153
+ This moves a story, bug, spike or task with `git mv` and commits only that move:
154
+ `ob: move 1.1.1 to doing`. That's the same commit a hand-run `git mv` and `git commit` would
155
+ make, so `git log --follow` shows the item's history across moves. With `done-folders: month` in
156
+ `config.yml`, done items go into `stories/done/YYYY-MM/`. Epics, features and capabilities don't
157
+ move: their status comes from their items.
158
+
159
+ - `--no-commit`: stage the `git mv` and leave committing to you.
160
+
161
+ ### ob list
162
+
163
+ ```sh
164
+ ob list [--status <s>] [--type <t>] [--parent <id>] [--repo <name>] [--assignee <h>] [--sprint <name>] [--all] [--json]
165
+ ```
166
+
167
+ This lists stories, bugs, spikes and tasks in build order (1.1.2 before 1.1.10). Each row has
168
+ the ID, status, repo (when the backlog lists repos) and title. Output is plain text with no
169
+ colour, and titles are cut to fit a terminal but never when piped. Done items show for 30 days
170
+ after the commit that moved them to done, and a note on stderr counts the older ones. Outside
171
+ git there are no dates, so every done item shows.
172
+
173
+ - `--status <s>`: `todo`, `doing` or `done`.
174
+ - `--type <t>`: `story`, `bug`, `spike` or `task`.
175
+ - `--parent <id>`: anything under this epic, feature or capability.
176
+ - `--repo <name>`, `--assignee <h>`, `--sprint <name>`: items with that repo, assignee or sprint.
177
+ - `--all`: done items of any age.
178
+ - `--json`: the same items with their fields, for other tools.
179
+
180
+ Each filter takes one value or several joined by commas (`--status todo,doing`), and filters
181
+ combine.
182
+
183
+ ### ob show
184
+
185
+ ```sh
186
+ ob show <id> [--json]
187
+ ```
188
+
189
+ This prints an item's place in the plan (`1-checkout › 1.1-pay-by-card › 1.1.1-card-form`), its
190
+ file's path and status, and the file itself. Then come its children, with a progress line for a
191
+ capability, epic or feature ("1/2 done (50%), 0 doing, 1 todo"), and every commit that touched
192
+ it. An ID removed with `git rm` is found in git history and shown as its last version, marked
193
+ deleted, with the commit that removed it.
194
+
195
+ - `--json`: the same, as JSON.
196
+
197
+ ### ob tree
198
+
199
+ ```sh
200
+ ob tree [--depth <n>] [--all] [--json]
201
+ ```
202
+
203
+ This prints the plan: capabilities, epics and features with their status and `done/total
204
+ (percent)`, and the items under them, in build order. Done items older than 30 days are left
205
+ out, as in `ob list`, but the counts include them.
206
+
207
+ - `--depth <n>`: show `n` levels (1 shows the top items only).
208
+ - `--all`: done items of any age.
209
+ - `--json`: the same tree, nested, as JSON.
210
+
211
+ ### ob validate
212
+
213
+ ```sh
214
+ ob validate [--fix] [--no-commit] [--json]
215
+ ```
216
+
217
+ This checks every file against the spec and prints each problem as
218
+ `<file>: <code> [<rule>] <what is wrong>. Fix: <how>.` It exits 1 when there are errors
219
+ (warnings alone exit 0), so it works in CI and as a git hook.
220
+
221
+ - `--fix`: renumber duplicate IDs. When two branches each add the next number, the item added
222
+ later in git history gets the next free number and its file is renamed with `git mv`. Children
223
+ that came with it get the new parent. It's one commit: `ob: renumber 1.1.1 to 1.1.2`.
224
+ - `--no-commit`: with `--fix`, leave committing to you.
225
+ - `--json`: `{ backlog, valid, errors, warnings, problems, renumbered }`, for other tools.
226
+
227
+ ## Checking the backlog in a hook and in CI
228
+
229
+ To refuse a commit that breaks the backlog, add a pre-commit hook. Save this as
230
+ `.git/hooks/pre-commit` and make it executable with `chmod +x`:
231
+
232
+ ```sh
233
+ #!/bin/sh
234
+ exec ob validate
235
+ ```
236
+
237
+ The hook checks the working tree, so a fix you haven't staged still counts. In CI, such as a
238
+ GitHub Actions step:
239
+
240
+ ```yaml
241
+ - run: npx --yes -p open-backlog ob validate
242
+ ```
243
+
244
+ ## Validation codes
245
+
246
+ Each rule in the spec has a code that never changes meaning.
247
+
248
+ | Code | Rule | | Code | Rule |
249
+ |---|---|---|---|---|
250
+ | OB001 | parent | | OB010 | not-stored |
251
+ | OB002 | parent-exists | | OB011 | no-email |
252
+ | OB003 | id-form | | OB012 | comment-line |
253
+ | OB004 | id-unique | | OB013 | sprints |
254
+ | OB005 | epic-zero | | OB014 | people |
255
+ | OB006 | filename | | OB015 | item-folder |
256
+ | OB007 | front-matter | | OB016 | config |
257
+ | OB008 | fields | | OB017 | local-clones (a warning) |
258
+ | OB009 | repo-listed | | | |
259
+
260
+ Single-file rules use the spec's JSON Schema, which ships in this package under `schema/0.1/`, so
261
+ `ob` agrees with any other tool that uses it.
262
+
263
+ ## Git
264
+
265
+ `ob` runs your own `git`, so your identity, keys, hooks and settings all apply, and it needs no
266
+ token. Each command commits only the files it changed, never anything else you have staged.
267
+ Outside a git repository, everything except committing still works.
268
+
269
+ ## The library
270
+
271
+ The same core that `ob` uses can be imported for scripts and other tools:
272
+
273
+ ```js
274
+ import { readBacklog, validateDir, buildTree, progressOf } from 'open-backlog';
275
+
276
+ const backlog = readBacklog(); // finds backlog/ from the working directory up
277
+ const { problems } = validateDir(backlog.dir);
278
+ ```
279
+
280
+ It also covers writing items without reformatting them (`setFields`, `updateItem`,
281
+ `createItem`), ordering (`buildOrder`), git (`moveItem`, `nextId`, `history`) and the commands'
282
+ own functions (`initBacklog`, `addItem`, `listItems`, `showItem`, `fixDuplicates`). It ships
283
+ TypeScript types.
284
+
285
+ ## Develop
286
+
287
+ To work on `ob` itself, from a clone of backlog-cli:
288
+
289
+ ```sh
290
+ npm install
291
+ npm run check # lint, build, test and smoke test: what CI runs on every push
292
+ npm test # just the tests
293
+ npm install -g . # ob on your PATH, from this checkout (after npm run build)
294
+ ```
295
+
296
+ | Path | |
297
+ |---|---|
298
+ | `src/core/` | the library. It never imports the CLI (lint enforces this), so other tools can use it on its own |
299
+ | `src/cli/` | the `ob` command, on top of the core. `main.ts` is the bin, and `run.ts` does the work and is what tests call |
300
+ | `test/` | Vitest tests. `test/fixtures/` holds backlog-spec's example backlogs, copied by `script/sync-spec.sh` |
301
+ | `schema/` | backlog-spec's JSON Schema, copied by `script/sync-spec.sh` |
302
+ | `script/smoke.mjs` | packs the package, checks its file list, installs it globally into a temporary folder and runs the commands |
303
+
304
+ To release, change `version` in `package.json` (`npm version patch --no-git-tag-version`),
305
+ commit and push to `main`. The publish workflow sees a version that isn't on npm yet, runs the
306
+ full check, publishes it and tags the commit `v<version>`. Any other push publishes nothing.
307
+
308
+ ## License
309
+
310
+ MIT. The specification is CC BY 4.0.
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,18 @@
1
+ #!/usr/bin/env node
2
+ // The ob command: everything is in run.ts, which tests call directly.
3
+ import { report, run } from './run.js';
4
+ // A reader that stops early (ob list | head) closes the pipe: not an error, so ob stops quietly
5
+ // with its own exit code instead of printing a stack trace.
6
+ for (const stream of [process.stdout, process.stderr]) {
7
+ stream.on('error', (e) => {
8
+ if (e.code !== 'EPIPE')
9
+ throw e;
10
+ process.exit();
11
+ });
12
+ }
13
+ try {
14
+ process.exitCode = run(process.argv.slice(2));
15
+ }
16
+ catch (e) {
17
+ process.exitCode = report(e);
18
+ }
@@ -0,0 +1,27 @@
1
+ /** Where ob writes (stdout and stderr, or a test's buffers), and what it runs with; tests set them. */
2
+ export interface Output {
3
+ out: (text: string) => void;
4
+ err: (text: string) => void;
5
+ cwd?: string;
6
+ env?: NodeJS.ProcessEnv;
7
+ now?: Date;
8
+ /** The terminal's width when writing to one; undefined when piped, so nothing is cut. */
9
+ columns?: number;
10
+ }
11
+ /** The package's own version, from its package.json (two folders up from src/cli/ or dist/cli/). */
12
+ export declare function packageVersion(): string;
13
+ export declare function usage(): string;
14
+ /** Every command with its long options, in --help order (the README documents each one). */
15
+ export declare function commandOptions(): Record<string, string[]>;
16
+ /**
17
+ * Runs ob with its arguments (without "node" and the script) and returns the exit code:
18
+ * 0 done, 1 the command failed (a BacklogError, from report), 2 bad usage. Writes nothing to
19
+ * process directly, so tests can call it.
20
+ */
21
+ export declare function run(args: string[], io?: Output): number;
22
+ /**
23
+ * What ob prints for an error that escapes a command, and its exit code: a backlog that can't be
24
+ * read (no config.yml, a file that isn't YAML) is one line naming the file, never a stack trace.
25
+ * Anything else is a bug in ob, so it keeps its stack.
26
+ */
27
+ export declare function report(e: unknown, io?: Output): number;