monoban 1.2.0 → 1.4.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 (3) hide show
  1. package/README.md +3 -0
  2. package/dist/index.mjs +129 -10
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -21,12 +21,15 @@ monoban add "Write the docs" -c todo # -d "text", -d - (stdin) or -e ($EDITOR)
21
21
  monoban add "Fix login" -t bug # -t tags it (repeat for more; a new name makes a tag); --date fri plans it
22
22
  monoban show MON-12
23
23
  monoban log MON-12 # what happened to it, newest first (-n 50 for more)
24
+ monoban comment MON-12 "Started on it" # a comment, in Markdown; - reads it from stdin
25
+ monoban comments MON-12 # its latest comments, oldest of them first (-n for how many)
24
26
  monoban today # what's planned for today in every project, overdue first (or: today fri --week)
25
27
  monoban search login bug # tasks with all the words, in every project (title, description, tag, MON-12)
26
28
  monoban schedule MON-12 fri # plan it for a day: tomorrow, next week, +3, oct 12… (--clear takes it off)
27
29
  monoban start MON-12 # in the repo: check out mon-12-title (from the commit you're on), move it to In progress
28
30
  monoban move MON-12 in-progress # columns match loosely: any case, a unique prefix
29
31
  monoban move MON-12 --to WEB # to another project (MON-12 becomes WEB-7); add a column to choose it
32
+ monoban move MON-12 todo --if-column-since 2026-10-14T10:00:00Z # only if it's been in its column since then
30
33
  monoban done MON-12
31
34
  monoban edit MON-12 # title and description in $EDITOR (or --title, -d, no editor)
32
35
  monoban tag MON-12 bug ui # untag MON-12 bug takes one off; list --tag bug filters
package/dist/index.mjs CHANGED
@@ -5395,7 +5395,10 @@ const LIMITS = {
5395
5395
  projectNotes: 1e5,
5396
5396
  linksPerTask: 20,
5397
5397
  linkUrl: 2e3,
5398
- linkTitle: 200
5398
+ linkTitle: 200,
5399
+ /** A comment on a task, in characters. */
5400
+ commentBody: 2e4,
5401
+ commentsPerTask: 500
5399
5402
  };
5400
5403
  //#endregion
5401
5404
  //#region ../../packages/contract/src/dates.ts
@@ -6204,6 +6207,21 @@ strictObject({
6204
6207
  */
6205
6208
  state: _enum(LINK_STATES).nullable().optional()
6206
6209
  }).meta({ id: "TaskLinkCreate" });
6210
+ /** A comment: Markdown, kept as written (not trimmed), and not blank. */
6211
+ const commentBody = string().min(1, "Required").max(LIMITS.commentBody).regex(/^[^\u0000]*$/, "Can't contain NUL characters");
6212
+ object({
6213
+ id: IdSchema,
6214
+ body: string(),
6215
+ /** What wrote it: `web`, `cli` or `api` (another client). */
6216
+ via: string().nullable(),
6217
+ version: Version,
6218
+ createdAt: Timestamp
6219
+ }).meta({ id: "TaskComment" });
6220
+ strictObject({
6221
+ /** Chosen by the client (a random uuid) so it can show the comment before the answer; 409 if taken. */
6222
+ id: IdSchema.optional(),
6223
+ body: commentBody
6224
+ }).meta({ id: "TaskCommentCreate" });
6207
6225
  strictObject({
6208
6226
  /** Chosen by the client (a random uuid) so it can show and edit the new item before the answer; 409 if taken. */
6209
6227
  id: IdSchema.optional(),
@@ -6378,7 +6396,11 @@ discriminatedUnion("kind", [
6378
6396
  event("transferred", {
6379
6397
  from: EventPlace,
6380
6398
  to: EventPlace
6381
- })
6399
+ }),
6400
+ event("commented", { comment: object({
6401
+ id: IdSchema,
6402
+ excerpt: string()
6403
+ }).meta({ id: "EventComment" }) })
6382
6404
  ]).meta({ id: "TaskEvent" });
6383
6405
  /**
6384
6406
  * Every list takes `?limit=` and `?cursor=` and answers `{ <items>: [...], nextCursor }` (keyset
@@ -7195,6 +7217,10 @@ function describeEvent(event, now = today()) {
7195
7217
  verb: "restored",
7196
7218
  detail: event.column ? `to ${event.column.name}` : ""
7197
7219
  };
7220
+ case "commented": return {
7221
+ verb: "commented",
7222
+ detail: event.comment.excerpt
7223
+ };
7198
7224
  }
7199
7225
  }
7200
7226
  const MINUTE = 6e4;
@@ -7301,7 +7327,7 @@ strictObject({ email: email().max(254).meta({ example: "ada@example.com" }) }).m
7301
7327
  //#endregion
7302
7328
  //#region src/version.ts
7303
7329
  /** This CLI's version, from package.json (set at build time by tsdown, and by vitest in tests). */
7304
- const VERSION = "1.2.0";
7330
+ const VERSION = "1.4.0";
7305
7331
  /** Sent as X-Monoban-Client, and shown in Devices & tokens. */
7306
7332
  const CLIENT = `cli/${VERSION}`;
7307
7333
  //#endregion
@@ -11240,15 +11266,83 @@ function changedElsewhere(err, ref) {
11240
11266
  if (err instanceof ApiProblem && err.status === 412) throw new CliError(`${ref} changed elsewhere in the meantime. Run \`monoban show ${ref}\` and try again.`);
11241
11267
  throw err;
11242
11268
  }
11243
- /** A task as the CLI prints it in JSON: the API's fields plus its column's name and its tags' names. */
11269
+ /**
11270
+ * A task as the CLI prints it in JSON: the API's fields plus its column's name, whether that's the Done
11271
+ * column (doneColumn: named Done, else the last), and its tags' names.
11272
+ */
11244
11273
  const taskJson = (task, columns, tags) => ({
11245
11274
  ...task,
11246
11275
  column: columns.find((c) => c.id === task.columnId)?.name ?? null,
11276
+ done: task.columnId === doneColumn(columns)?.id,
11247
11277
  tags: tagsOfTask(task, tags).map((t) => t.name)
11248
11278
  });
11249
11279
  /** Where the web shows a project's board, or one task on it. */
11250
11280
  const boardUrl = (ctx, key, number) => `${ctx.webUrl}/p/${key}${number === void 0 ? "" : `?task=${number}`}`;
11251
11281
  //#endregion
11282
+ //#region src/commands/comments.ts
11283
+ /** `monoban comment MON-12 TEXT…`: a comment on the task (`-` reads it from stdin, Markdown and all). */
11284
+ async function comment(ctx, ref, words, options) {
11285
+ const body = words.length === 1 && words[0] === "-" ? (await ctx.readStdin()).replace(/\n$/, "") : words.join(" ");
11286
+ if (!body.trim()) throw new CliError("Nothing to say: give the text, or - to read it from stdin.", EXIT.usage);
11287
+ const api = apis(ctx).signedIn;
11288
+ const task = await taskByRef(api, ref, ctx);
11289
+ const { key, number } = taskRefOf(task.ref);
11290
+ const added = await unwrap(api.POST("/v1/projects/{key}/tasks/{number}/comments", {
11291
+ params: { path: {
11292
+ key,
11293
+ number
11294
+ } },
11295
+ body: { body }
11296
+ }));
11297
+ if (options.json) return ctx.out(JSON.stringify(added, null, 2));
11298
+ ctx.out(`Commented on ${task.ref}.`);
11299
+ }
11300
+ /** `monoban comments MON-12`: the latest comments (`-n`, 20 unless you say), oldest of them first. */
11301
+ async function comments(ctx, ref, options) {
11302
+ const count = options.number === void 0 ? 20 : Number(options.number);
11303
+ if (!Number.isInteger(count) || count < 1) throw new CliError("-n is how many comments to show: 1 or more.", EXIT.usage);
11304
+ const api = apis(ctx).signedIn;
11305
+ const task = await taskByRef(api, ref, ctx);
11306
+ const all = await commentsOf(api, task.ref);
11307
+ const shown = all.slice(-count);
11308
+ if (options.json) return ctx.out(JSON.stringify(shown, null, 2));
11309
+ if (!shown.length) {
11310
+ ctx.err(`${task.ref} has no comments yet. Add one with \`monoban comment ${task.ref} …\`.`);
11311
+ return;
11312
+ }
11313
+ for (const line of commentLines(shown, ctx.style)) ctx.out(line);
11314
+ if (all.length > shown.length) ctx.err(`Older comments too: -n ${all.length} shows all ${all.length}.`);
11315
+ }
11316
+ /** All of a task's comments, oldest first, a page at a time: a task has a few hundred at most. */
11317
+ async function commentsOf(api, ref) {
11318
+ const { key, number } = taskRefOf(ref);
11319
+ const all = [];
11320
+ let cursor;
11321
+ do {
11322
+ const page = await unwrap(api.GET("/v1/projects/{key}/tasks/{number}/comments", { params: {
11323
+ path: {
11324
+ key,
11325
+ number
11326
+ },
11327
+ query: {
11328
+ limit: PAGE_LIMIT.max,
11329
+ cursor
11330
+ }
11331
+ } }));
11332
+ all.push(...page.comments);
11333
+ cursor = page.nextCursor ?? void 0;
11334
+ } while (cursor);
11335
+ return all;
11336
+ }
11337
+ /** Each comment under a "── 2h · cli" rule, a blank line between them. */
11338
+ function commentLines(comments, { dim }, now = Date.now()) {
11339
+ return comments.flatMap((m, i) => [
11340
+ ...i ? [""] : [],
11341
+ dim(`── ${eventAge(m.createdAt, now)}${m.via ? ` · ${m.via}` : ""}`),
11342
+ ...m.body.replace(/\n+$/, "").split("\n")
11343
+ ]);
11344
+ }
11345
+ //#endregion
11252
11346
  //#region src/commands/history.ts
11253
11347
  /** The newest `count` events of a task (a page at a time), and whether it has older ones. */
11254
11348
  async function historyOf(api, ref, count) {
@@ -11513,17 +11607,19 @@ const ago = (iso) => {
11513
11607
  const a = age(iso);
11514
11608
  return a === "today" ? a : `${a} ago`;
11515
11609
  };
11516
- /** How many history events `show` ends with. */
11610
+ /** How many history events and comments `show` ends with. */
11517
11611
  const SHOW_HISTORY = 3;
11612
+ const SHOW_COMMENTS = 2;
11518
11613
  /** `monoban show MON-12`: a task in full, and what happened to it last. */
11519
11614
  async function show(ctx, ref, options) {
11520
11615
  const api = apis(ctx).signedIn;
11521
11616
  const task = await taskByRef(api, ref, ctx);
11522
11617
  const key = taskRefOf(task.ref).key;
11523
- const [columns, tags, history] = await Promise.all([
11618
+ const [columns, tags, history, comments] = await Promise.all([
11524
11619
  columnsOf(api, key),
11525
11620
  tagsFor(api, key, task),
11526
- options.json ? null : historyOf(api, task.ref, SHOW_HISTORY).catch(() => null)
11621
+ options.json ? null : historyOf(api, task.ref, SHOW_HISTORY).catch(() => null),
11622
+ options.json ? null : commentsOf(api, task.ref).catch(() => null)
11527
11623
  ]);
11528
11624
  if (options.json) return printJson$1(ctx, taskJson(task, columns, tags));
11529
11625
  const { bold, dim } = ctx.style;
@@ -11548,6 +11644,12 @@ async function show(ctx, ref, options) {
11548
11644
  ctx.out("");
11549
11645
  ctx.out(task.description.trimEnd());
11550
11646
  }
11647
+ if (comments?.length) {
11648
+ const more = comments.length > SHOW_COMMENTS;
11649
+ ctx.out("");
11650
+ ctx.out(dim(more ? `Comments (all ${comments.length}: monoban comments ${task.ref})` : "Comments"));
11651
+ for (const line of commentLines(comments.slice(-2), ctx.style)) ctx.out(line && ` ${line}`);
11652
+ }
11551
11653
  if (history?.events.length) {
11552
11654
  ctx.out("");
11553
11655
  ctx.out(dim(history.more ? `History (all of it: monoban log ${task.ref})` : "History"));
@@ -11671,6 +11773,7 @@ async function tags(ctx, options) {
11671
11773
  async function move(ctx, ref, columnQuery, options) {
11672
11774
  const api = apis(ctx).signedIn;
11673
11775
  const task = await taskByRef(api, ref, ctx);
11776
+ if (options.ifColumnSince !== void 0) unmovedSince(task, options.ifColumnSince);
11674
11777
  const { key } = taskRefOf(task.ref);
11675
11778
  const to = options.to?.trim().toUpperCase();
11676
11779
  if (to && to !== key) return transfer(ctx, api, task, to, columnQuery, options);
@@ -11681,6 +11784,15 @@ async function move(ctx, ref, columnQuery, options) {
11681
11784
  const columns = await columnsOf(api, key);
11682
11785
  await moveTo(ctx, api, task, columns, findColumn(columns, columnQuery), options);
11683
11786
  }
11787
+ /**
11788
+ * --if-column-since: only a task still in the column it arrived in at `since` (its columnSince then). The
11789
+ * write that follows carries the version this read saw, so a move in between is a 412 too.
11790
+ */
11791
+ function unmovedSince(task, since) {
11792
+ const at = Date.parse(since);
11793
+ if (Number.isNaN(at)) throw new CliError(`--if-column-since takes a time like 2026-10-14T10:00:00Z (a task's columnSince).`, EXIT.usage);
11794
+ if (Date.parse(task.columnSince) !== at) throw new CliError(`${task.ref} changed elsewhere in the meantime: it has been in its column since ${task.columnSince}, not ${since}.`);
11795
+ }
11684
11796
  /** Moves a task to project `to` (its column `columnQuery`, if given). */
11685
11797
  async function transfer(ctx, api, task, to, columnQuery, options) {
11686
11798
  const columns = await columnsOf(api, to);
@@ -12097,6 +12209,7 @@ const READ_ONLY = [
12097
12209
  "monoban ls",
12098
12210
  "monoban show",
12099
12211
  "monoban log",
12212
+ "monoban comments",
12100
12213
  "monoban today",
12101
12214
  "monoban search",
12102
12215
  "monoban tags",
@@ -12130,7 +12243,7 @@ plans into tasks on the board and to keep those tasks current while you work.
12130
12243
  that project. Otherwise \`monoban projects\` lists the keys; pass \`-p KEY\` to project commands. If it's
12131
12244
  unclear which project the work belongs to, ask. Suggest \`monoban link KEY\` to the user rather than
12132
12245
  running it (it changes the project).
12133
- 3. Read with \`--json\`: \`monoban list --json\` (every task, with its \`column\` and \`tags\`),
12246
+ 3. Read with \`--json\`: \`monoban list --json\` (every task, with its \`column\`, \`done\` and \`tags\`),
12134
12247
  \`monoban show MON-12 --json\`, \`monoban tags --json\`, and \`monoban notes show\` for the notes.
12135
12248
  \`monoban log MON-12\` shows what happened to a task, when, and through what (web or cli).
12136
12249
  \`monoban search WORDS\` finds a task in any project ("the login bug": \`monoban search login bug\`).
@@ -12197,6 +12310,8 @@ go?"). Once the user agrees:
12197
12310
  \`monoban move MON-31 "in progress"\` (columns match in any case, or by a unique prefix).
12198
12311
  - Ticking the checklist: read the description (\`monoban show MON-31 --json\`), change \`- [ ]\` to \`- [x]\`,
12199
12312
  and write the whole description back with \`monoban edit MON-31 -d -\` (stdin, a heredoc as above).
12313
+ - Worth telling whoever reads the task later (a decision, a blocker, what's left): \`monoban comment MON-31 -\`
12314
+ with the Markdown on stdin. Comments can't be edited, so keep them few and finished.
12200
12315
  - Opened a pull request for it: \`monoban attach MON-31 --pr\` right after \`gh pr create\` (on a branch named
12201
12316
  after the task, like \`mon-31-invoices\`, \`monoban attach --pr\` finds the task itself). The card shows it.
12202
12317
  - Finished: \`monoban done MON-31\`, when the work is really done by the user's standard (tests pass, merged,
@@ -12224,6 +12339,7 @@ go?"). Once the user agrees:
12224
12339
  | \`monoban list [COLUMN…] [--tag TAG] [--archived]\` | tasks by column (--archived: the ones done long ago) |
12225
12340
  | \`monoban show MON-12\` | one task in full |
12226
12341
  | \`monoban log MON-12 [-n COUNT]\` | what happened to it, newest first |
12342
+ | \`monoban comments MON-12 [-n COUNT]\` | its latest comments |
12227
12343
  | \`monoban today [DAY] [--week]\` | what's planned for today (overdue first) in every project |
12228
12344
  | \`monoban search WORDS… [-n COUNT]\` | tasks with all the words, in every project, last changed first |
12229
12345
  | \`monoban schedule MON-12 DAY\` (or \`--clear\`) | plan it for a day: today, tomorrow, fri, +3, oct 12 |
@@ -12237,6 +12353,7 @@ go?"). Once the user agrees:
12237
12353
  | \`monoban done MON-12\` | move it to Done |
12238
12354
  | \`monoban tag MON-12 TAG…\` / \`monoban untag MON-12 TAG…\` | put tags on it / take them off |
12239
12355
  | \`monoban attach MON-12 --pr\` or \`monoban attach MON-12 URL\` | attach this branch's pull request, or any link |
12356
+ | \`monoban comment MON-12 TEXT\` (or \`-\` for stdin) | comment on it, in Markdown |
12240
12357
  | \`monoban notes add TEXT\` (or \`-\` for stdin) | add lines at the end of the notes |
12241
12358
 
12242
12359
  Every command takes \`--json\`; project commands take \`-p KEY\`. \`monoban COMMAND --help\` has the rest.
@@ -12642,7 +12759,7 @@ async function latestVersion(ctx) {
12642
12759
  async function upgrade(ctx, options, kind = thisInstall()) {
12643
12760
  const latest = await latestVersion(ctx);
12644
12761
  const { how, command } = UPGRADE[kind];
12645
- const outdated = latest !== null && newer(latest, "1.2.0");
12762
+ const outdated = latest !== null && newer(latest, "1.4.0");
12646
12763
  if (options.json) {
12647
12764
  ctx.out(JSON.stringify({
12648
12765
  version: VERSION,
@@ -12674,11 +12791,13 @@ function program(ctx) {
12674
12791
  cli.command("list").alias("ls").argument("[columns...]", "only these columns (any case; a prefix works: `back`, `inp`)").description("Show the board's tasks by column").option("-t, --tag <tag>", "only tasks with this tag").option("--archived", "the archived tasks instead (done a while ago, off the board)").addOption(project()).addOption(json()).action(async (columns, options) => list(await ctx(), columns, options));
12675
12792
  cli.command("show").argument("<task>", "like MON-12").description("Show a task: title, column, tags, checklist and description").addOption(json()).action(async (ref, options) => show(await ctx(), ref, options));
12676
12793
  cli.command("log").argument("<task>", "like MON-12").description("Show what happened to a task, newest first: created, moved, edited, tags, links").option("-n, --number <count>", "how many events (default 20)").addOption(json()).action(async (ref, options) => log(await ctx(), ref, options));
12794
+ cli.command("comment").argument("<task>", "like MON-12").argument("<text...>", "what to say, in Markdown (- reads it from stdin)").description("Comment on a task").addOption(json()).action(async (ref, words, options) => comment(await ctx(), ref, words, options));
12795
+ cli.command("comments").argument("<task>", "like MON-12").description("Show a task's latest comments, oldest of them first").option("-n, --number <count>", "how many comments (default 20)").addOption(json()).action(async (ref, options) => comments(await ctx(), ref, options));
12677
12796
  cli.command("add").argument("<title>").description("Add a task (to the end of the first column, or of -c)").option("-c, --column <column>", "the column to add it to").option("-d, --description <text>", "its description (- reads it from stdin)").option("-e, --edit", "write the description in $EDITOR").option("-t, --tag <tag>", "a tag (repeat for more; a new name makes a tag)", collect).option("--date <day>", "the day to do it: today, tomorrow, fri, +3, oct 12…").addOption(project()).addOption(json()).action(async (title, options) => add(await ctx(), title, options));
12678
12797
  cli.command("today").argument("[day]", "another day: tomorrow, fri, oct 12, 2026-10-12…").description("Show what's planned for today in every project (overdue first), or for another day").option("-w, --week", "the 7 days from it").addOption(json()).action(async (day, options) => todayView(await ctx(), day, options));
12679
12798
  cli.command("search").argument("<words...>", "all of them: in the title or description, a tag, or a reference like MON-12").description("Find tasks in every project, the last changed first").option("-n, --number <count>", "how many tasks (default 30)").addOption(json()).action(async (words, options) => search(await ctx(), words, options));
12680
12799
  cli.command("schedule").argument("<task>", "like MON-12").argument("[day]", "today, tomorrow, fri, next week, +3, oct 12, 2026-10-12…").description("Plan a task for a day (it shows in `monoban today` then), or take its date off with --clear").option("--clear", "take the date off").addOption(json()).action(async (ref, day, options) => schedule(await ctx(), ref, day, options));
12681
- cli.command("move").argument("<task>", "like MON-12").argument("[column]", "where to (any case; a prefix works)").description("Move a task to the end of another column, or (--to) to another project").option("--to <project>", "another project's key: the task gets a number there (MON-12 becomes WEB-7)").addOption(json()).action(async (ref, column, options) => move(await ctx(), ref, column, options));
12800
+ cli.command("move").argument("<task>", "like MON-12").argument("[column]", "where to (any case; a prefix works)").description("Move a task to the end of another column, or (--to) to another project").option("--to <project>", "another project's key: the task gets a number there (MON-12 becomes WEB-7)").option("--if-column-since <time>", "only if it's been in its column since then (its columnSince): nobody moved it").addOption(json()).action(async (ref, column, options) => move(await ctx(), ref, column, options));
12682
12801
  cli.command("done").argument("<task>", "like MON-12").description("Move a task to Done (or the last column)").addOption(json()).action(async (ref, options) => done(await ctx(), ref, options));
12683
12802
  cli.command("start").argument("<task>", "like MON-12").description("Start a task: check out its branch (mon-12-title, made from the commit you're on) and move it to In progress").option("--no-branch", "only move it").option("--no-move", "only check out its branch").addOption(json()).action(async (ref, options) => start(await ctx(), ref, options));
12684
12803
  cli.command("edit").argument("<task>", "like MON-12").description("Edit a task's title (the first line) and description in $EDITOR, or set them with --title and -d").option("--title <text>", "a new title (no editor)").option("-d, --description <text>", "a new description, replacing it (- reads it from stdin; no editor)").addOption(json()).action(async (ref, options) => edit(await ctx(), ref, options));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "monoban",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "A keyboard-first kanban board in your terminal: list, add and move tasks on monoban.dev.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://monoban.dev",