open-backlog 0.1.1 → 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.
package/README.md CHANGED
@@ -81,6 +81,17 @@ $ ob validate
81
81
  backlog/ is valid, 7 items
82
82
  ```
83
83
 
84
+ Leave a comment on it. `ob` signs it with your handle, which you set once in git; it never
85
+ writes your email:
86
+
87
+ ```sh
88
+ $ git config --global ob.handle ana
89
+ $ ob comment 1.1.1 "Card form done; tested on Safari"
90
+ Commented on 1.1.1: backlog/stories/done/1.1.1-card-form.md
91
+ - 2026-11-21 @ana: Card form done; tested on Safari
92
+ Committed: ob: comment on 1.1.1
93
+ ```
94
+
84
95
  Open `backlog/stories/todo/1.1.2-save-the-card.md` in any editor to write the story. `ob show
85
96
  1.1.2` prints it with where it sits in the plan and its history. Push, and your team has the
86
97
  backlog with the code.
@@ -158,6 +169,26 @@ move: their status comes from their items.
158
169
 
159
170
  - `--no-commit`: stage the `git mv` and leave committing to you.
160
171
 
172
+ ### ob comment
173
+
174
+ ```sh
175
+ ob comment <id> <text> [--as <handle>] [--no-commit]
176
+ ```
177
+
178
+ This adds `- YYYY-MM-DD @handle: text` under the item's `## Comments`, making the section at the
179
+ end if there is none. It's the same line you would add by hand, and nothing else in the file
180
+ changes. It commits that file alone: `ob: comment on 1.1.1`. It works on any item: a story, bug,
181
+ spike or task in any folder, a feature, an epic or a capability. Comments live in the file, so
182
+ they move with the story.
183
+
184
+ The handle comes from `git config ob.handle`; set it once with
185
+ `git config --global ob.handle <handle>`. `ob` never uses your git email or name, so no email
186
+ address is written to the file, and it refuses a comment whose text holds one.
187
+
188
+ - `--as <handle>`: sign it with this handle instead.
189
+ - `--no-commit`: write the line and leave committing to you. Without it, `ob comment` refuses a
190
+ file that already has uncommitted changes, so the commit holds only the comment.
191
+
161
192
  ### ob list
162
193
 
163
194
  ```sh
@@ -187,12 +218,12 @@ ob show <id> [--json]
187
218
  ```
188
219
 
189
220
  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
221
+ file's path and status, how many comments it has, and the file itself, comments included. Then come its children, with a progress line for a
191
222
  capability, epic or feature ("1/2 done (50%), 0 doing, 1 todo"), and every commit that touched
192
223
  it. An ID removed with `git rm` is found in git history and shown as its last version, marked
193
224
  deleted, with the commit that removed it.
194
225
 
195
- - `--json`: the same, as JSON.
226
+ - `--json`: the same, as JSON, with the comments as a list (date, handle, text).
196
227
 
197
228
  ### ob tree
198
229
 
@@ -264,6 +295,7 @@ Single-file rules use the spec's JSON Schema, which ships in this package under
264
295
 
265
296
  `ob` runs your own `git`, so your identity, keys, hooks and settings all apply, and it needs no
266
297
  token. Each command commits only the files it changed, never anything else you have staged.
298
+ `ob` never writes your git email or name into the backlog; comments are signed with a handle.
267
299
  Outside a git repository, everything except committing still works.
268
300
 
269
301
  ## The library
@@ -279,7 +311,7 @@ const { problems } = validateDir(backlog.dir);
279
311
 
280
312
  It also covers writing items without reformatting them (`setFields`, `updateItem`,
281
313
  `createItem`), ordering (`buildOrder`), git (`moveItem`, `nextId`, `history`) and the commands'
282
- own functions (`initBacklog`, `addItem`, `listItems`, `showItem`, `fixDuplicates`). It ships
314
+ own functions (`initBacklog`, `addItem`, `addComment`, `listItems`, `showItem`, `fixDuplicates`). It ships
283
315
  TypeScript types.
284
316
 
285
317
  ## Develop
package/dist/cli/run.js CHANGED
@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
2
2
  import { readFileSync, realpathSync } from 'node:fs';
3
3
  import { join, relative } from 'node:path';
4
4
  import { parseArgs } from 'node:util';
5
- import { addItem, BacklogError, buildTree, commit, findBacklog, fixDuplicates, formatProblem, initBacklog, initDir, isStoryLevel, ITEM_TYPES, listItems, loadBacklog, message, moveItem, progressOf, recentlyDone, reposOf, repoRoot, showItem, SPEC_URL, SPEC_VERSION, validateDir } from '../core/index.js';
5
+ import { addComment, addItem, BacklogError, buildTree, commit, findBacklog, fixDuplicates, formatProblem, initBacklog, initDir, isStoryLevel, ITEM_TYPES, listItems, loadBacklog, message, moveItem, progressOf, recentlyDone, reposOf, repoRoot, showItem, SPEC_URL, SPEC_VERSION, validateDir } from '../core/index.js';
6
6
  const STD = {
7
7
  out: t => process.stdout.write(t),
8
8
  err: t => process.stderr.write(t),
@@ -207,6 +207,44 @@ their items.
207
207
  return moveCommand(id, 'done', values, io, 'done');
208
208
  },
209
209
  },
210
+ comment: {
211
+ summary: 'add a dated, signed comment to an item, in one commit',
212
+ help: `Usage: ob comment <id> <text> [--as <handle>] [--no-commit]
213
+
214
+ Adds "- YYYY-MM-DD @handle: text" under the item's ## Comments (making the section at the end if
215
+ there is none), the same line you would add by hand, and commits that file alone:
216
+ "ob: comment on 2.3.4". Any item: a story, bug, spike or task in any folder, a feature, an
217
+ epic or a capability.
218
+
219
+ ob comment 2.3.4 "Started; testing on beta"
220
+
221
+ The handle is from git config ob.handle (set it once: git config --global ob.handle jo-smith),
222
+ never your git email, so no email address is written to the file.
223
+
224
+ --as <handle> sign it with this handle instead
225
+ --no-commit write the line, leave committing to you
226
+ `,
227
+ options: { as: { type: 'string' }, 'no-commit': { type: 'boolean' } },
228
+ run: (values, positionals, io) => {
229
+ const [id, ...words] = positionals;
230
+ if (id === undefined || !words.length)
231
+ return usageError('ob comment needs an id and the text, such as: ob comment 2.3.4 "Started"', 'comment', io);
232
+ const cwd = realpathSync(io.cwd ?? process.cwd());
233
+ const b = loadBacklog(findBacklog(cwd));
234
+ const r = addComment(b, id, {
235
+ text: words.join(' '),
236
+ ...(typeof values['as'] === 'string' ? { handle: values['as'] } : {}),
237
+ commit: values['no-commit'] !== true,
238
+ ...(io.now ? { day: io.now } : {}),
239
+ });
240
+ io.out(`Commented on ${id}: ${relative(cwd, join(b.dir, r.path))}\n${r.line}\n`);
241
+ if (r.committed)
242
+ io.out(`Committed: ${message.comment(id)}\n`);
243
+ else if (values['no-commit'] === true)
244
+ io.out('Not committed (--no-commit).\n');
245
+ return 0;
246
+ },
247
+ },
210
248
  list: {
211
249
  summary: 'list stories, bugs, spikes and tasks in build order, filtered',
212
250
  help: `Usage: ob list [filters] [--all] [--json]
@@ -273,9 +311,9 @@ Each filter takes one value or several joined by commas (--status todo,doing).
273
311
  summary: 'show an item: where it sits, its file, children, progress and history',
274
312
  help: `Usage: ob show <id> [--json]
275
313
 
276
- Prints the item's place in the plan (2-build › 2.3-cli › 2.3.4-ob-move), its file, its file's
277
- text, its children (with progress, for a capability, epic or feature) and the commits that
278
- touched it. An ID pruned with git rm is found in git history: its last version, marked deleted.
314
+ Prints the item's place in the plan (2-build › 2.3-cli › 2.3.4-ob-move), its file, how many
315
+ comments it has, its file's text (comments included), its children (with progress, for a
316
+ capability, epic or feature) and the commits that touched it. An ID pruned with git rm is found in git history: its last version, marked deleted.
279
317
 
280
318
  --json the same, as JSON, for other tools
281
319
  `,
@@ -300,6 +338,9 @@ touched it. An ID pruned with git rm is found in git history: its last version,
300
338
  lines.push(`Progress: ${progressText(s.progress)}, ${s.progress.doing} doing, ${s.progress.todo} todo`);
301
339
  if (s.sameId.length)
302
340
  lines.push(`Also id ${id}: ${s.sameId.join(', ')} (run ob validate --fix)`);
341
+ const lastComment = s.comments[s.comments.length - 1];
342
+ if (lastComment)
343
+ lines.push(`Comments: ${s.comments.length}, the last on ${lastComment.date} by @${lastComment.handle}`);
303
344
  lines.push('', s.text.trimEnd());
304
345
  if (s.children.length) {
305
346
  const w = Math.max(...s.children.map(c => c.id.length));
@@ -0,0 +1,50 @@
1
+ import type { Backlog } from './types.js';
2
+ /**
3
+ * Comments (2.3.9): one line under the item's `## Comments`, `- YYYY-MM-DD @handle: text`
4
+ * ([comment-line]), the same line you would add by hand, and one commit. Signed with a handle,
5
+ * never an email address ([no-email]): the handle comes from --as or `git config ob.handle`,
6
+ * never from git's user.email or user.name.
7
+ */
8
+ /** A handle (spec, Fields): lowercase letters, digits, -, _ and ., such as jo-smith. */
9
+ export declare const HANDLE_PATTERN: RegExp;
10
+ export interface Comment {
11
+ date: string;
12
+ handle: string;
13
+ /** The comment, with any continuation lines joined by "\n" (their indent removed). */
14
+ text: string;
15
+ }
16
+ export interface CommentOptions {
17
+ text: string;
18
+ /** Who signs it; by default `git config ob.handle`. */
19
+ handle?: string;
20
+ /** The day it's dated (default today, local time). */
21
+ day?: Date;
22
+ /** Commit it (default true; nothing to commit outside git). */
23
+ commit?: boolean;
24
+ }
25
+ export interface Commented {
26
+ id: string;
27
+ /** The item's file, from the backlog folder. */
28
+ path: string;
29
+ /** The line added (its first line, for a comment over several lines). */
30
+ line: string;
31
+ committed: boolean;
32
+ }
33
+ /** The handle git is set up with (`git config ob.handle`, local or global), or null. */
34
+ export declare function configuredHandle(dir: string): string | null;
35
+ /** "2026-11-22" in local time. */
36
+ export declare function dayOf(day: Date): string;
37
+ /**
38
+ * The file with the comment added: after the last line of `## Comments` (before any heading that
39
+ * follows it), or, with no such section, a new one at the end. Every other byte is kept, and the
40
+ * file's own line endings are used. A text over several lines continues on lines indented two
41
+ * spaces.
42
+ */
43
+ export declare function withComment(file: string, comment: Comment): string;
44
+ /** The comments under an item's `## Comments`, oldest first; lines that aren't comments are skipped. */
45
+ export declare function commentsOf(file: string): Comment[];
46
+ /**
47
+ * Adds a comment to an item, any type, in any folder, and commits that file alone:
48
+ * "ob: comment on 2.3.4". Everything is checked first; a BacklogError writes nothing.
49
+ */
50
+ export declare function addComment(b: Backlog, id: string, opts: CommentOptions): Commented;
@@ -0,0 +1,115 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { readFileSync, writeFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { changes, commit, message } from './git.js';
5
+ import { BacklogError } from './types.js';
6
+ /**
7
+ * Comments (2.3.9): one line under the item's `## Comments`, `- YYYY-MM-DD @handle: text`
8
+ * ([comment-line]), the same line you would add by hand, and one commit. Signed with a handle,
9
+ * never an email address ([no-email]): the handle comes from --as or `git config ob.handle`,
10
+ * never from git's user.email or user.name.
11
+ */
12
+ /** A handle (spec, Fields): lowercase letters, digits, -, _ and ., such as jo-smith. */
13
+ export const HANDLE_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
14
+ const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
15
+ const HEADING = /^## Comments[ \t]*$/;
16
+ /** The handle git is set up with (`git config ob.handle`, local or global), or null. */
17
+ export function configuredHandle(dir) {
18
+ try {
19
+ const h = execFileSync('git', ['config', '--get', 'ob.handle'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
20
+ return h || null;
21
+ }
22
+ catch {
23
+ return null;
24
+ }
25
+ }
26
+ /** "2026-11-22" in local time. */
27
+ export function dayOf(day) {
28
+ return `${day.getFullYear()}-${String(day.getMonth() + 1).padStart(2, '0')}-${String(day.getDate()).padStart(2, '0')}`;
29
+ }
30
+ /**
31
+ * The file with the comment added: after the last line of `## Comments` (before any heading that
32
+ * follows it), or, with no such section, a new one at the end. Every other byte is kept, and the
33
+ * file's own line endings are used. A text over several lines continues on lines indented two
34
+ * spaces.
35
+ */
36
+ export function withComment(file, comment) {
37
+ const nl = file.includes('\r\n') ? '\r\n' : '\n';
38
+ const lines = `- ${comment.date} @${comment.handle}: ${comment.text.split(/\r?\n/).join(`${nl} `)}`;
39
+ const head = file.split(/\r?\n/).findIndex(l => HEADING.test(l));
40
+ if (head === -1) {
41
+ // A new section at the end, after a blank line, as you would type it.
42
+ let s = file;
43
+ if (s && !s.endsWith(nl))
44
+ s += nl;
45
+ if (s && !s.endsWith(nl + nl))
46
+ s += nl;
47
+ return `${s}## Comments${nl}${lines}${nl}`;
48
+ }
49
+ const all = file.split(/\r?\n/);
50
+ // The section runs to the next heading (# or ##) or the end; the comment goes after its last
51
+ // line that isn't blank, so blank lines before a following heading stay where they are.
52
+ let end = all.findIndex((l, i) => i > head && /^#{1,2} /.test(l));
53
+ if (end === -1)
54
+ end = all.length;
55
+ let last = end - 1;
56
+ while (last > head && (all[last] ?? '').trim() === '')
57
+ last--;
58
+ all.splice(last + 1, 0, lines);
59
+ return all.join(nl);
60
+ }
61
+ /** The comments under an item's `## Comments`, oldest first; lines that aren't comments are skipped. */
62
+ export function commentsOf(file) {
63
+ const all = file.split(/\r?\n/);
64
+ const head = all.findIndex(l => HEADING.test(l));
65
+ if (head === -1)
66
+ return [];
67
+ const out = [];
68
+ let current = null;
69
+ for (const l of all.slice(head + 1)) {
70
+ if (/^#{1,2} /.test(l))
71
+ break;
72
+ const m = /^- (\d{4}-\d{2}-\d{2}) @([a-z0-9][a-z0-9._-]*): ?(.*)$/.exec(l);
73
+ if (m)
74
+ out.push(current = { date: m[1] ?? '', handle: m[2] ?? '', text: m[3] ?? '' });
75
+ else if (current && /^\s+\S/.test(l))
76
+ current.text += `\n${l.trim()}`;
77
+ // Anything else ends a comment; a list item that isn't one is ob validate's to report.
78
+ else if (l.trim())
79
+ current = null;
80
+ }
81
+ return out;
82
+ }
83
+ /**
84
+ * Adds a comment to an item, any type, in any folder, and commits that file alone:
85
+ * "ob: comment on 2.3.4". Everything is checked first; a BacklogError writes nothing.
86
+ */
87
+ export function addComment(b, id, opts) {
88
+ const found = b.items.filter(i => i.id === id);
89
+ const item = found[0];
90
+ if (!item)
91
+ throw new BacklogError(`no item ${id} in this backlog`);
92
+ if (found.length > 1)
93
+ throw new BacklogError(`${found.length} items have id ${id} (${found.map(i => i.path).join(', ')}); run ob validate --fix first`);
94
+ const text = opts.text.replace(/\s+$/, '').replace(/^\s+/, '');
95
+ if (!text)
96
+ throw new BacklogError('a comment needs some text');
97
+ if (EMAIL.test(text))
98
+ throw new BacklogError('a comment can\'t hold an email address ([no-email]); name people by handle, such as @jo-smith');
99
+ const handle = (opts.handle ?? configuredHandle(b.dir) ?? '').replace(/^@/, '');
100
+ if (!handle) {
101
+ throw new BacklogError('who is commenting? Set your handle once with: git config --global ob.handle <handle> (such as jo-smith), or pass --as <handle>. ob never uses your git email');
102
+ }
103
+ if (!HANDLE_PATTERN.test(handle))
104
+ throw new BacklogError(`"${handle}" is not a handle: use lowercase letters, digits, -, _ and ., such as jo-smith`);
105
+ const abs = join(b.dir, item.path);
106
+ const wantCommit = opts.commit !== false;
107
+ if (wantCommit && changes(b.dir, [abs]).length) {
108
+ throw new BacklogError(`${item.path} has changes that aren't committed; commit them first, or add the comment with --no-commit`);
109
+ }
110
+ const before = readFileSync(abs, 'utf8');
111
+ const comment = { date: dayOf(opts.day ?? new Date()), handle, text };
112
+ writeFileSync(abs, withComment(before, comment));
113
+ const committed = wantCommit ? commit([abs], message.comment(id)) : false;
114
+ return { id, path: item.path, line: `- ${comment.date} @${handle}: ${text.split(/\r?\n/)[0]}`, committed };
115
+ }
@@ -13,6 +13,7 @@ export declare const message: {
13
13
  move: (id: string, status: Status) => string;
14
14
  add: (id: string, title: string) => string;
15
15
  edit: (id: string, what: string) => string;
16
+ comment: (id: string) => string;
16
17
  renumber: (changes: {
17
18
  from: string;
18
19
  to: string;
package/dist/core/git.js CHANGED
@@ -35,6 +35,7 @@ export const message = {
35
35
  move: (id, status) => `ob: move ${id} to ${status}`,
36
36
  add: (id, title) => `ob: add ${id} ${title}`,
37
37
  edit: (id, what) => `ob: edit ${id} ${what}`,
38
+ comment: (id) => `ob: comment on ${id}`,
38
39
  renumber: (changes) => `ob: renumber ${changes.map(c => `${c.from} to ${c.to}`).join(', ')}`,
39
40
  };
40
41
  /**
@@ -12,6 +12,8 @@
12
12
  export { SPEC_URL, SPEC_VERSION } from './spec.js';
13
13
  export { addItem, ITEM_TYPES, SLUG_PATTERN, UNPLANNED_TYPES } from './add.js';
14
14
  export type { AddOptions, Added } from './add.js';
15
+ export { addComment, commentsOf, configuredHandle, dayOf, HANDLE_PATTERN, withComment } from './comment.js';
16
+ export type { Comment, CommentOptions, Commented } from './comment.js';
15
17
  export { fixDuplicates } from './fix.js';
16
18
  export type { Renumbered } from './fix.js';
17
19
  export { addedIn, changes, commit, git, history, isAncestor, isClean, message, monthOf, move, moveItem, nextId, pull, push, repoRoot, statusPath, usedIds } from './git.js';
@@ -11,6 +11,7 @@
11
11
  */
12
12
  export { SPEC_URL, SPEC_VERSION } from './spec.js';
13
13
  export { addItem, ITEM_TYPES, SLUG_PATTERN, UNPLANNED_TYPES } from './add.js';
14
+ export { addComment, commentsOf, configuredHandle, dayOf, HANDLE_PATTERN, withComment } from './comment.js';
14
15
  export { fixDuplicates } from './fix.js';
15
16
  export { addedIn, changes, commit, git, history, isAncestor, isClean, message, monthOf, move, moveItem, nextId, pull, push, repoRoot, statusPath, usedIds } from './git.js';
16
17
  export { initBacklog, initDir, INIT_FOLDERS, INIT_README, NAME_PATTERN } from './init.js';
@@ -1,3 +1,4 @@
1
+ import type { Comment } from './comment.js';
1
2
  import type { LogEntry } from './git.js';
2
3
  import type { Progress } from './hierarchy.js';
3
4
  import type { Backlog, Status } from './types.js';
@@ -33,6 +34,8 @@ export interface Shown {
33
34
  deleted: LogEntry | null;
34
35
  /** Other items with the same ID ([id-unique]), if any. */
35
36
  sameId: string[];
37
+ /** The comments under `## Comments`, oldest first (2.3.9). */
38
+ comments: Comment[];
36
39
  }
37
40
  /** An item, or a pruned one from git history; a BacklogError if the ID was never used. */
38
41
  export declare function showItem(b: Backlog, id: string): Shown;
package/dist/core/show.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
+ import { commentsOf } from './comment.js';
3
4
  import { git, history, repoRoot } from './git.js';
4
5
  import { buildTree, isStoryLevel, progressOf } from './hierarchy.js';
5
6
  import { parseFileName } from './ids.js';
@@ -28,11 +29,12 @@ export function showItem(b, id) {
28
29
  };
29
30
  if (node) {
30
31
  const item = node.item;
32
+ const text = readFileSync(join(b.dir, item.path), 'utf8');
31
33
  return {
32
34
  id, type: item.type, title: item.title, path: item.path, breadcrumb: crumbs(item, stem(item.path)),
33
- status: item.status ?? null, fields: item.fields, text: readFileSync(join(b.dir, item.path), 'utf8'),
35
+ status: item.status ?? null, fields: item.fields, text,
34
36
  progress: isStoryLevel(item) ? null : progressOf(node), children: childrenOf(id),
35
- history: history(join(b.dir, item.path)), deleted: null, sameId,
37
+ history: history(join(b.dir, item.path)), deleted: null, sameId, comments: commentsOf(text),
36
38
  };
37
39
  }
38
40
  const pruned = findPruned(b, id);
@@ -45,7 +47,7 @@ export function showItem(b, id) {
45
47
  return {
46
48
  id, type, title: String(fields['title'] ?? ''), path: pruned.path, breadcrumb: crumbs(ghost, stem(pruned.path)),
47
49
  status: statusOf(pruned.path) ?? null, fields, text: pruned.text, progress: null, children: childrenOf(id),
48
- history: pruned.history, deleted: pruned.deleted, sameId: [],
50
+ history: pruned.history, deleted: pruned.deleted, sameId: [], comments: commentsOf(pruned.text),
49
51
  };
50
52
  }
51
53
  /** The newest commit that removed an item file with this ID (and didn't add it back elsewhere: a move). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "open-backlog",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Open Backlog: a backlog as Markdown files in git. The ob command, and the core library it is built on.",
5
5
  "license": "MIT",
6
6
  "author": "Brandon Castagna",