things-api 0.8.0 → 0.10.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 (238) hide show
  1. package/README.md +31 -11
  2. package/dist/audit/log.js +56 -2
  3. package/dist/audit/log.js.map +1 -1
  4. package/dist/audit/schema.d.ts +26 -8
  5. package/dist/audit/schema.js +42 -1
  6. package/dist/audit/schema.js.map +1 -1
  7. package/dist/cli/commands/area.d.ts +34 -2
  8. package/dist/cli/commands/area.js +140 -28
  9. package/dist/cli/commands/area.js.map +1 -1
  10. package/dist/cli/commands/doctor.d.ts +1 -1
  11. package/dist/cli/commands/doctor.js +44 -5
  12. package/dist/cli/commands/doctor.js.map +1 -1
  13. package/dist/cli/commands/mcp.js +23 -4
  14. package/dist/cli/commands/mcp.js.map +1 -1
  15. package/dist/cli/commands/project.d.ts +23 -1
  16. package/dist/cli/commands/project.js +82 -15
  17. package/dist/cli/commands/project.js.map +1 -1
  18. package/dist/cli/commands/reads.d.ts +6 -125
  19. package/dist/cli/commands/reads.js +649 -657
  20. package/dist/cli/commands/reads.js.map +1 -1
  21. package/dist/cli/commands/repeat-flags.d.ts +20 -0
  22. package/dist/cli/commands/repeat-flags.js +76 -0
  23. package/dist/cli/commands/repeat-flags.js.map +1 -0
  24. package/dist/cli/commands/setup.js +2 -3
  25. package/dist/cli/commands/setup.js.map +1 -1
  26. package/dist/cli/commands/show.d.ts +1 -1
  27. package/dist/cli/commands/show.js +169 -18
  28. package/dist/cli/commands/show.js.map +1 -1
  29. package/dist/cli/commands/snapshot.js +1 -1
  30. package/dist/cli/commands/snapshot.js.map +1 -1
  31. package/dist/cli/commands/todo.d.ts +1 -1
  32. package/dist/cli/commands/todo.js +21 -9
  33. package/dist/cli/commands/todo.js.map +1 -1
  34. package/dist/cli/commands/writes.js +378 -148
  35. package/dist/cli/commands/writes.js.map +1 -1
  36. package/dist/cli/did-you-mean.d.ts +29 -0
  37. package/dist/cli/did-you-mean.js +53 -0
  38. package/dist/cli/did-you-mean.js.map +1 -0
  39. package/dist/cli/excess-args.d.ts +15 -0
  40. package/dist/cli/excess-args.js +51 -0
  41. package/dist/cli/excess-args.js.map +1 -0
  42. package/dist/cli/glyphs.d.ts +67 -7
  43. package/dist/cli/glyphs.js +202 -19
  44. package/dist/cli/glyphs.js.map +1 -1
  45. package/dist/cli/help.d.ts +54 -0
  46. package/dist/cli/help.js +355 -0
  47. package/dist/cli/help.js.map +1 -0
  48. package/dist/cli/main.js +36 -21
  49. package/dist/cli/main.js.map +1 -1
  50. package/dist/cli/period.d.ts +39 -0
  51. package/dist/cli/period.js +141 -0
  52. package/dist/cli/period.js.map +1 -0
  53. package/dist/cli/read-driver.d.ts +83 -0
  54. package/dist/cli/read-driver.js +215 -0
  55. package/dist/cli/read-driver.js.map +1 -0
  56. package/dist/cli/render.d.ts +246 -0
  57. package/dist/cli/render.js +806 -0
  58. package/dist/cli/render.js.map +1 -0
  59. package/dist/cli/resolve-invocation.d.ts +116 -0
  60. package/dist/cli/resolve-invocation.js +261 -0
  61. package/dist/cli/resolve-invocation.js.map +1 -0
  62. package/dist/cli/shell-quote.d.ts +9 -0
  63. package/dist/cli/shell-quote.js +12 -0
  64. package/dist/cli/shell-quote.js.map +1 -0
  65. package/dist/cli/tag-filters.d.ts +59 -0
  66. package/dist/cli/tag-filters.js +57 -0
  67. package/dist/cli/tag-filters.js.map +1 -0
  68. package/dist/cli/verb-hint.d.ts +25 -0
  69. package/dist/cli/verb-hint.js +138 -0
  70. package/dist/cli/verb-hint.js.map +1 -0
  71. package/dist/cli/width.d.ts +135 -0
  72. package/dist/cli/width.js +313 -0
  73. package/dist/cli/width.js.map +1 -0
  74. package/dist/client.d.ts +146 -24
  75. package/dist/client.js +106 -16
  76. package/dist/client.js.map +1 -1
  77. package/dist/config.d.ts +11 -0
  78. package/dist/config.js +3 -0
  79. package/dist/config.js.map +1 -1
  80. package/dist/contracts.d.ts +136 -1
  81. package/dist/contracts.js +44 -1
  82. package/dist/contracts.js.map +1 -1
  83. package/dist/db/fingerprint.d.ts +12 -0
  84. package/dist/db/fingerprint.js +15 -1
  85. package/dist/db/fingerprint.js.map +1 -1
  86. package/dist/db/locate.js +1 -1
  87. package/dist/db/locate.js.map +1 -1
  88. package/dist/diagnose.d.ts +63 -0
  89. package/dist/diagnose.js +38 -1
  90. package/dist/diagnose.js.map +1 -1
  91. package/dist/index.d.ts +30 -4
  92. package/dist/index.js +35 -2
  93. package/dist/index.js.map +1 -1
  94. package/dist/mcp/server.d.ts +9 -1
  95. package/dist/mcp/server.js +850 -128
  96. package/dist/mcp/server.js.map +1 -1
  97. package/dist/model/entities.d.ts +40 -7
  98. package/dist/model/entities.js.map +1 -1
  99. package/dist/model/mappers.d.ts +7 -0
  100. package/dist/model/mappers.js +20 -3
  101. package/dist/model/mappers.js.map +1 -1
  102. package/dist/model/occurrences.d.ts +6 -1
  103. package/dist/model/occurrences.js +9 -5
  104. package/dist/model/occurrences.js.map +1 -1
  105. package/dist/model/recurrence.d.ts +17 -8
  106. package/dist/model/recurrence.js.map +1 -1
  107. package/dist/model/serialize.d.ts +28 -0
  108. package/dist/model/serialize.js +80 -0
  109. package/dist/model/serialize.js.map +1 -0
  110. package/dist/model/when-sugar.d.ts +47 -0
  111. package/dist/model/when-sugar.js +45 -0
  112. package/dist/model/when-sugar.js.map +1 -0
  113. package/dist/read/area-view.d.ts +8 -1
  114. package/dist/read/area-view.js +49 -13
  115. package/dist/read/area-view.js.map +1 -1
  116. package/dist/read/caps.d.ts +14 -0
  117. package/dist/read/caps.js +21 -0
  118. package/dist/read/caps.js.map +1 -0
  119. package/dist/read/filter-contract.d.ts +117 -0
  120. package/dist/read/filter-contract.js +78 -0
  121. package/dist/read/filter-contract.js.map +1 -0
  122. package/dist/read/log-boundary.d.ts +9 -4
  123. package/dist/read/log-boundary.js.map +1 -1
  124. package/dist/read/predicates.d.ts +61 -0
  125. package/dist/read/predicates.js +78 -0
  126. package/dist/read/predicates.js.map +1 -0
  127. package/dist/read/project-view.d.ts +12 -1
  128. package/dist/read/project-view.js +39 -8
  129. package/dist/read/project-view.js.map +1 -1
  130. package/dist/read/queries.d.ts +156 -8
  131. package/dist/read/queries.js +261 -38
  132. package/dist/read/queries.js.map +1 -1
  133. package/dist/read/search-rank.d.ts +36 -0
  134. package/dist/read/search-rank.js +31 -0
  135. package/dist/read/search-rank.js.map +1 -0
  136. package/dist/read/sections.d.ts +51 -0
  137. package/dist/read/sections.js +37 -0
  138. package/dist/read/sections.js.map +1 -0
  139. package/dist/read/show-target.d.ts +13 -4
  140. package/dist/read/show-target.js +11 -2
  141. package/dist/read/show-target.js.map +1 -1
  142. package/dist/read/sidebar-order.d.ts +19 -0
  143. package/dist/read/sidebar-order.js +93 -0
  144. package/dist/read/sidebar-order.js.map +1 -0
  145. package/dist/read/tags.d.ts +27 -3
  146. package/dist/read/tags.js +83 -12
  147. package/dist/read/tags.js.map +1 -1
  148. package/dist/read/truncation.d.ts +71 -0
  149. package/dist/read/truncation.js +217 -0
  150. package/dist/read/truncation.js.map +1 -0
  151. package/dist/read/views.d.ts +177 -19
  152. package/dist/read/views.js +390 -213
  153. package/dist/read/views.js.map +1 -1
  154. package/dist/surface-copy.d.ts +42 -0
  155. package/dist/surface-copy.js +55 -0
  156. package/dist/surface-copy.js.map +1 -1
  157. package/dist/sync-health.d.ts +78 -0
  158. package/dist/sync-health.js +312 -0
  159. package/dist/sync-health.js.map +1 -0
  160. package/dist/write/accessibility-probe.d.ts +12 -0
  161. package/dist/write/accessibility-probe.js +63 -0
  162. package/dist/write/accessibility-probe.js.map +1 -0
  163. package/dist/write/automation-probe.d.ts +7 -0
  164. package/dist/write/automation-probe.js +8 -1
  165. package/dist/write/automation-probe.js.map +1 -1
  166. package/dist/write/batch.js +4 -2
  167. package/dist/write/batch.js.map +1 -1
  168. package/dist/write/capabilities.d.ts +8 -0
  169. package/dist/write/capabilities.js +13 -5
  170. package/dist/write/capabilities.js.map +1 -1
  171. package/dist/write/commands.d.ts +2 -0
  172. package/dist/write/commands.js +562 -48
  173. package/dist/write/commands.js.map +1 -1
  174. package/dist/write/edit-checklist.js +3 -2
  175. package/dist/write/edit-checklist.js.map +1 -1
  176. package/dist/write/guards.d.ts +2 -7
  177. package/dist/write/guards.js +64 -6
  178. package/dist/write/guards.js.map +1 -1
  179. package/dist/write/heading.js +2 -0
  180. package/dist/write/heading.js.map +1 -1
  181. package/dist/write/lock.d.ts +40 -2
  182. package/dist/write/lock.js +91 -14
  183. package/dist/write/lock.js.map +1 -1
  184. package/dist/write/make-repeating-project.d.ts +4 -0
  185. package/dist/write/make-repeating-project.js +253 -0
  186. package/dist/write/make-repeating-project.js.map +1 -0
  187. package/dist/write/operations.d.ts +145 -1
  188. package/dist/write/operations.js +48 -0
  189. package/dist/write/operations.js.map +1 -1
  190. package/dist/write/pipeline.d.ts +19 -0
  191. package/dist/write/pipeline.js +109 -26
  192. package/dist/write/pipeline.js.map +1 -1
  193. package/dist/write/pre-state.d.ts +68 -3
  194. package/dist/write/pre-state.js +102 -3
  195. package/dist/write/pre-state.js.map +1 -1
  196. package/dist/write/reopen.js +3 -2
  197. package/dist/write/reopen.js.map +1 -1
  198. package/dist/write/reorder.js +27 -17
  199. package/dist/write/reorder.js.map +1 -1
  200. package/dist/write/repeat-rule.d.ts +22 -0
  201. package/dist/write/repeat-rule.js +258 -0
  202. package/dist/write/repeat-rule.js.map +1 -0
  203. package/dist/write/reversibility.js +49 -0
  204. package/dist/write/reversibility.js.map +1 -1
  205. package/dist/write/tag-refs.d.ts +47 -0
  206. package/dist/write/tag-refs.js +126 -0
  207. package/dist/write/tag-refs.js.map +1 -0
  208. package/dist/write/undo.d.ts +74 -5
  209. package/dist/write/undo.js +494 -80
  210. package/dist/write/undo.js.map +1 -1
  211. package/dist/write/vectors/registry.d.ts +17 -1
  212. package/dist/write/vectors/registry.js +18 -2
  213. package/dist/write/vectors/registry.js.map +1 -1
  214. package/dist/write/vectors/types.d.ts +119 -3
  215. package/dist/write/vectors/ui-certification.d.ts +48 -0
  216. package/dist/write/vectors/ui-certification.js +46 -0
  217. package/dist/write/vectors/ui-certification.js.map +1 -0
  218. package/dist/write/vectors/ui-drag.d.ts +188 -0
  219. package/dist/write/vectors/ui-drag.js +1095 -0
  220. package/dist/write/vectors/ui-drag.js.map +1 -0
  221. package/dist/write/vectors/ui-recipes.d.ts +70 -0
  222. package/dist/write/vectors/ui-recipes.js +558 -0
  223. package/dist/write/vectors/ui-recipes.js.map +1 -0
  224. package/dist/write/vectors/ui.d.ts +137 -0
  225. package/dist/write/vectors/ui.js +656 -0
  226. package/dist/write/vectors/ui.js.map +1 -0
  227. package/dist/write/verify/delta.d.ts +31 -3
  228. package/dist/write/verify/delta.js +22 -6
  229. package/dist/write/verify/delta.js.map +1 -1
  230. package/dist/write/verify/poller.js +1 -0
  231. package/dist/write/verify/poller.js.map +1 -1
  232. package/package.json +1 -1
  233. package/dist/cli/exit-codes.d.ts +0 -26
  234. package/dist/cli/exit-codes.js +0 -26
  235. package/dist/cli/exit-codes.js.map +0 -1
  236. package/dist/cli/output.d.ts +0 -42
  237. package/dist/cli/output.js +0 -16
  238. package/dist/cli/output.js.map +0 -1
@@ -1,4 +1,4 @@
1
- import { blue, bold, brightBlue, dim, green, red, yellow } from "./style.js";
1
+ import { blue, bold, brightBlue, dim, green, red, strike, underline, yellow } from "./style.js";
2
2
  const MONTHS = [
3
3
  "Jan",
4
4
  "Feb",
@@ -13,12 +13,23 @@ const MONTHS = [
13
13
  "Nov",
14
14
  "Dec",
15
15
  ];
16
+ const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
16
17
  /** `Jul 31` — the year is appended only when it differs from today's. */
17
18
  export function shortDate(iso, todayIso) {
18
19
  const [y, m, d] = iso.split("-").map(Number);
19
20
  const label = `${MONTHS[(m ?? 1) - 1]} ${d}`;
20
21
  return String(y) === todayIso.slice(0, 4) ? label : `${label} ${y}`;
21
22
  }
23
+ /**
24
+ * `Fri, Aug 28` — the GUI's detail-header date form: weekday abbreviation +
25
+ * month + day, the year appended only when it differs from today's (same
26
+ * convention as {@link shortDate} / the ‹date› chip).
27
+ */
28
+ export function weekdayDate(iso, todayIso) {
29
+ const [y, m, d] = iso.split("-").map(Number);
30
+ const weekday = WEEKDAYS[new Date(Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1)).getUTCDay()];
31
+ return `${weekday}, ${shortDate(iso, todayIso)}`;
32
+ }
22
33
  /** The GUI's grey schedule pill: `‹Jul 31›` on future-scheduled rows. */
23
34
  export function dateChip(iso, todayIso) {
24
35
  return dim(`‹${shortDate(iso, todayIso)}›`);
@@ -43,8 +54,10 @@ export function todoBox(item) {
43
54
  // brackets (still a to-do) but seat ↻ INSIDE them so the row reads as
44
55
  // "the recurring one" at a glance, distinct from its spawned instances
45
56
  // (which are ordinary [ ] rows). Never someday, though the DB stores it so.
57
+ // The box stays PLAIN — the GUI's repeat pseudo-checkbox is white, and the ↻
58
+ // inside already marks the rule row (no muting).
46
59
  if (item.repeating.isTemplate)
47
- return dim("[↻]");
60
+ return "[↻]";
48
61
  if (item.start === "someday" && item.startDate === null)
49
62
  return dim("[~]");
50
63
  return "[ ]";
@@ -60,21 +73,53 @@ export function projectCircle(item) {
60
73
  return blue("(✓)");
61
74
  if (item.status === "canceled")
62
75
  return blue("(×)");
63
- // Repeating project template: ↻ inside the circle (the to-do rule above).
76
+ // Repeating project template: ↻ inside the circle. A template is still a
77
+ // project, so its circle keeps the blue accent — the GUI shows a solid blue
78
+ // circle with the arrow, not a muted glyph.
64
79
  if (item.repeating.isTemplate)
65
- return dim("(↻)");
80
+ return blue("(↻)");
81
+ // Someday projects are muted like someday to-dos — the GUI greys a someday
82
+ // project the same way. Its type is still carried by the round bracket and
83
+ // the bold title (projectTitleAccent), so the circle spends dim, not blue.
84
+ if (item.start === "someday" && item.startDate === null)
85
+ return dim("(~)");
66
86
  // Open projects render blue — GUI parity (the sidebar/list accent) and a
67
87
  // second, color-independent cue on top of the round bracket that this row
68
88
  // is a project, not a to-do.
69
- if (item.start === "someday" && item.startDate === null)
70
- return blue("(~)");
71
89
  return blue("( )");
72
90
  }
91
+ /**
92
+ * THE SINGLE LAW for project-title WEIGHT and COLOR in list rows (ratified
93
+ * 2026-07-13, docs/design/render-language.md).
94
+ *
95
+ * Project titles are BOLD and DEFAULT-colored (white) in every view and every
96
+ * state. The round bracket plus this bold weight already carry "this row is a
97
+ * project", so the row never spends the blue channel (reserved for the project
98
+ * checkbox accent and the completed/canceled marks) merely restating its own
99
+ * type. Every project-title call site routes through here — formatItem and the
100
+ * hand-built project-header lines — so reverting to blue (or bold-blue) is a
101
+ * one-line change to this function, nowhere else.
102
+ */
103
+ export function projectTitleAccent(title) {
104
+ return bold(title);
105
+ }
73
106
  /** Progress chip on project rows: `‹remaining/total›` (the GUI shows only the remaining count). */
74
107
  export function countChip(item) {
75
108
  const total = item.untrashedLeafActionsCount;
76
109
  return dim(total === 0 ? "‹0›" : `‹${item.openUntrashedLeafActionsCount}/${total}›`);
77
110
  }
111
+ /**
112
+ * The `inherited:` line VALUE for the detail/card surfaces (`todo show`,
113
+ * `project show`): the inherited tag NAMES plainly — `#important #home`. The
114
+ * whole value renders DIM (secondary metadata — distinct from the opened item's
115
+ * OWN tags, which render green): inherited tags are context, not the item's own
116
+ * assignments. No container provenance chip. The array is already in canonical
117
+ * tag order (inheritedTagsFor). Never rendered on list rows, and callers omit
118
+ * the line entirely when empty.
119
+ */
120
+ export function inheritedChips(inherited) {
121
+ return dim(`#${inherited.map((t) => t.title).join(" #")}`);
122
+ }
78
123
  /** Area marker (the GUI's green cube icon; a hexagon is a cube's silhouette). */
79
124
  export const areaMark = () => green("⬡");
80
125
  /** Whole-day difference between two ISO dates (positive = `to` is later). */
@@ -84,23 +129,29 @@ function daysBetween(fromIso, toIso) {
84
129
  return Math.round((Date.UTC(ty ?? 0, (tm ?? 1) - 1, td ?? 1) - Date.UTC(fy ?? 0, (fm ?? 1) - 1, fd ?? 1)) /
85
130
  86_400_000);
86
131
  }
87
- /** Uncapped relative phrasing: `today`, `3 days left`, `253 days ago`. */
88
- export function relativeDays(iso, todayIso) {
132
+ /**
133
+ * Uncapped relative phrasing for the detail-card deadline hint, GUI wording:
134
+ * `due today`, `46 days left`, `3 days overdue`.
135
+ */
136
+ function deadlineRelative(iso, todayIso) {
89
137
  const diff = daysBetween(todayIso, iso);
90
138
  if (diff === 0)
91
- return "today";
139
+ return "due today";
92
140
  return diff > 0
93
141
  ? `${diff} day${diff === 1 ? "" : "s"} left`
94
- : `${-diff} day${diff === -1 ? "" : "s"} ago`;
142
+ : `${-diff} day${diff === -1 ? "" : "s"} overdue`;
95
143
  }
96
144
  /**
97
- * Detail-card deadline line value (the GUI's "Deadline: Oct 30, 2025
98
- * 253 days ago" row): exact date plus uncapped relative phrasing. Bold red
99
- * once due; bold dim while upcoming.
145
+ * Detail-card deadline line value (to-do / project / area cards). GUI parity:
146
+ * the full `Fri, Aug 28` weekday date (year appended when not the current
147
+ * year), then a muted relative hint — `(46 days left)` / `(due today)` /
148
+ * `(3 days overdue)`. The date is bold red once due or overdue, bold otherwise;
149
+ * the hint is always muted. LIST rows keep the compact {@link deadlineToken}.
100
150
  */
101
151
  export function deadlineDetail(deadlineIso, todayIso) {
102
- const text = `⚑ ${shortDate(deadlineIso, todayIso)} (${relativeDays(deadlineIso, todayIso)})`;
103
- return daysBetween(todayIso, deadlineIso) <= 0 ? bold(red(text)) : bold(dim(text));
152
+ const date = weekdayDate(deadlineIso, todayIso);
153
+ const styledDate = daysBetween(todayIso, deadlineIso) <= 0 ? bold(red(date)) : bold(date);
154
+ return `${styledDate} ${dim(`(${deadlineRelative(deadlineIso, todayIso)})`)}`;
104
155
  }
105
156
  /** The share link the GUI's context menu copies — pasteable back into any ref argument. */
106
157
  export function thingsLink(uuid) {
@@ -135,20 +186,43 @@ export function whenValue(item, todayIso) {
135
186
  * past; `⚑ today` on the day), then the date shorthand — `Sep 16` within
136
187
  * the current year, `Feb 2027` beyond it. Overdue and due-today render
137
188
  * bold red; upcoming renders bold dim (the GUI's gray).
189
+ *
190
+ * `compact` selects the narrow forms the Things iOS app uses when the row is
191
+ * width-pinched (Mike's screenshot oracle, 2026-07-14) — the caller decides
192
+ * ONCE per view whether the gutter is compact (../cli/width.ts + render.ts's
193
+ * two floors), never per row, so a view's deadline column never mixes forms:
194
+ * - month-day absolutes shorten to `M/D` with NO zero-padding (`Aug 12` →
195
+ * `8/12`, `May 4` → `5/4`);
196
+ * - day-relatives shorten to `Nd left` / `Nd ago` (`58 days ago` → `58d ago`,
197
+ * `1 day left` → `1d left` — iOS shows no pluralization, so `1d`).
198
+ * Year-bearing FAR dates collapse to the YEAR alone in compact mode (`Feb
199
+ * 2027` → `2027`, `Oct 2020` → `2020`) — Mike's ruling 2026-07-14: unambiguous
200
+ * against M/D (always 4 digits), and at that distance the month carries little
201
+ * signal (docs/design/width-aware-tty.md § Compact deadline forms).
202
+ * `⚑ today` is already minimal and is unchanged.
138
203
  */
139
- export function deadlineToken(deadlineIso, todayIso) {
204
+ export function deadlineToken(deadlineIso, todayIso, compact = false) {
140
205
  const diff = daysBetween(todayIso, deadlineIso);
141
206
  let label;
142
207
  if (diff === 0)
143
208
  label = "today";
144
209
  else if (diff > 0 && diff <= 14)
145
- label = `${diff} day${diff === 1 ? "" : "s"} left`;
210
+ label = compact ? `${diff}d left` : `${diff} day${diff === 1 ? "" : "s"} left`;
146
211
  else if (diff < 0 && diff >= -59)
147
- label = `${-diff} day${diff === -1 ? "" : "s"} ago`;
212
+ label = compact ? `${-diff}d ago` : `${-diff} day${diff === -1 ? "" : "s"} ago`;
148
213
  else {
149
214
  const [y, m, d] = deadlineIso.split("-").map(Number);
150
215
  const month = MONTHS[(m ?? 1) - 1];
151
- label = String(y) === todayIso.slice(0, 4) ? `${month} ${d}` : `${month} ${y}`;
216
+ // Same-year month-day compacts to M/D; a year-bearing far date compacts
217
+ // to the YEAR alone (4 digits — unambiguous against M/D).
218
+ label =
219
+ String(y) === todayIso.slice(0, 4)
220
+ ? compact
221
+ ? `${m}/${d}`
222
+ : `${month} ${d}`
223
+ : compact
224
+ ? `${y}`
225
+ : `${month} ${y}`;
152
226
  }
153
227
  const chip = `⚑ ${label}`;
154
228
  return diff <= 0 ? bold(red(chip)) : bold(dim(chip));
@@ -166,4 +240,113 @@ export const CHECKLIST_MARK = "≔";
166
240
  /** Today star / This-Evening crescent, rendered after the box in today-aware views. */
167
241
  export const todayStar = () => yellow("★");
168
242
  export const eveningMoon = () => brightBlue("⏾");
243
+ export const LEGEND_GROUPS = [
244
+ "To-dos",
245
+ "Projects",
246
+ "Markers & chips",
247
+ "Colors & styles",
248
+ "Sections & hints",
249
+ ];
250
+ /**
251
+ * The rendered visual language, derived from the glyph helpers above so it
252
+ * documents what actually renders — never a hand-kept copy that can drift.
253
+ * Each `glyph` is a real sample built from the same styling the list rows use;
254
+ * `things legend` groups these for humans and `--json` emits them ANSI-stripped.
255
+ */
256
+ export const LEGEND = [
257
+ // To-dos — the [ ]-family box carries state with color stripped.
258
+ { glyph: "[ ]", meaning: "to-do, open", group: "To-dos" },
259
+ { glyph: blue("[✓]"), meaning: "to-do, completed", group: "To-dos" },
260
+ { glyph: blue("[×]"), meaning: "to-do, canceled (title struck through)", group: "To-dos" },
261
+ { glyph: dim("[~]"), meaning: "to-do, someday (undated)", group: "To-dos" },
262
+ {
263
+ glyph: "[↻]",
264
+ meaning: "repeating to-do — the rule itself (instances are ordinary [ ])",
265
+ group: "To-dos",
266
+ },
267
+ // Projects — round where to-dos are square; open rows render blue.
268
+ { glyph: blue("( )"), meaning: "project, open", group: "Projects" },
269
+ { glyph: blue("(✓)"), meaning: "project, completed", group: "Projects" },
270
+ { glyph: blue("(×)"), meaning: "project, canceled", group: "Projects" },
271
+ { glyph: dim("(~)"), meaning: "project, someday (undated)", group: "Projects" },
272
+ {
273
+ glyph: blue("(↻)"),
274
+ meaning: "repeating project — the recurring rule itself",
275
+ group: "Projects",
276
+ },
277
+ {
278
+ glyph: dim("‹2/5›"),
279
+ meaning: "project progress: remaining/total to-dos (‹0› when it has none)",
280
+ group: "Projects",
281
+ },
282
+ // Markers & chips — trail the title (bell, notes, checklist) or precede it.
283
+ { glyph: todayStar(), meaning: "Today member", group: "Markers & chips" },
284
+ { glyph: eveningMoon(), meaning: "This Evening member", group: "Markers & chips" },
285
+ {
286
+ glyph: bold(dim("⚑")),
287
+ meaning: "deadline — bold gray while upcoming, bold red once due or overdue",
288
+ group: "Markers & chips",
289
+ },
290
+ { glyph: dim(NOTES_MARK), meaning: "has notes", group: "Markers & chips" },
291
+ { glyph: dim(REMINDER_MARK), meaning: "has a reminder time", group: "Markers & chips" },
292
+ { glyph: dim(CHECKLIST_MARK), meaning: "has a checklist", group: "Markers & chips" },
293
+ { glyph: areaMark(), meaning: "area", group: "Markers & chips" },
294
+ {
295
+ glyph: dim("‹Jul 31›"),
296
+ meaning: "scheduled date, or ‹waiting›/‹paused›/‹ended› on a repeat template",
297
+ group: "Markers & chips",
298
+ },
299
+ {
300
+ glyph: green("#tag"),
301
+ meaning: "tag — muted on list rows, green on the opened item",
302
+ group: "Markers & chips",
303
+ },
304
+ // Colors & styles — enhancements on top of the shape; never the only cue.
305
+ {
306
+ glyph: dim("a1b2c3d4"),
307
+ meaning: "item id prefix (8+ chars; full id in --json) — pass to any command",
308
+ group: "Colors & styles",
309
+ },
310
+ {
311
+ glyph: dim("dim text"),
312
+ meaning: "later, hidden, inactive, or a resolved row out of place",
313
+ group: "Colors & styles",
314
+ },
315
+ {
316
+ glyph: strike("struck"),
317
+ meaning: "canceled item title (kept even in the Logbook)",
318
+ group: "Colors & styles",
319
+ },
320
+ {
321
+ glyph: blue("blue"),
322
+ meaning: "project checkbox accent, and the completed/canceled ✓ × marks",
323
+ group: "Colors & styles",
324
+ },
325
+ {
326
+ glyph: bold("bold"),
327
+ meaning: "project title — every row, every state",
328
+ group: "Colors & styles",
329
+ },
330
+ {
331
+ glyph: bold(underline("bold underline")),
332
+ meaning: "heading — a project heading its to-dos, or a section header",
333
+ group: "Colors & styles",
334
+ },
335
+ // Sections & hints — structure and the never-silent truncation notices.
336
+ {
337
+ glyph: bold("──"),
338
+ meaning: "section divider (area, Upcoming date bucket, Logbook month heading)",
339
+ group: "Sections & hints",
340
+ },
341
+ {
342
+ glyph: dim(" … 14 more — `…`"),
343
+ meaning: "a truncated block, indented; the command that shows more",
344
+ group: "Sections & hints",
345
+ },
346
+ {
347
+ glyph: dim("… 23 later items — `…`"),
348
+ meaning: "a whole hidden section, flush; the reveal command",
349
+ group: "Sections & hints",
350
+ },
351
+ ];
169
352
  //# sourceMappingURL=glyphs.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli/glyphs.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli/glyphs.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The help system (docs/design/cli-grammar.md, docs/design/surface-copy.md).
3
+ *
4
+ * Progressive disclosure for an agent with ZERO Things knowledge:
5
+ * - `things --help` / `things help` — a signpost INDEX: one line per command,
6
+ * grouped, under a hard line budget so it shows without scrolling.
7
+ * - `things help <topic>` — the guides that used to crowd the index (agent
8
+ * notes, filters, ids, output, writes).
9
+ * - `things <command> --help` — the per-command detail (commander's default).
10
+ *
11
+ * The index text lives here, not in each command's `.description()`: a command
12
+ * description is a paragraph for `things <command> --help`; the index needs a
13
+ * single ≤58-char behavioral line. A completeness test keeps the two in sync
14
+ * (every registered top-level command appears in exactly one group).
15
+ */
16
+ import type { Command } from "commander";
17
+ /** One command's index line: its argument sketch and its ≤58-char descriptor. */
18
+ interface IndexEntry {
19
+ /** Argument sketch shown after the name (`<ref>`, `[ref]`, `<verb>`), or "". */
20
+ args: string;
21
+ /** Behavioral one-liner (≤58 chars) — what the command does, not how. */
22
+ desc: string;
23
+ }
24
+ /** The index groups, in display order. Every top-level command lands in one. */
25
+ export declare const HELP_GROUPS: ReadonlyArray<{
26
+ title: string;
27
+ commands: readonly string[];
28
+ }>;
29
+ /**
30
+ * The per-command index copy. Keyed by top-level command name. Kept ≤58 chars
31
+ * and behavior-only (surface-copy.md); the completeness test asserts this map's
32
+ * keys are exactly the registered top-level commands (minus `help`).
33
+ */
34
+ export declare const INDEX: Readonly<Record<string, IndexEntry>>;
35
+ /** Resolve the width to reflow help to: THINGS_WIDTH, else the TTY, else 100. */
36
+ export declare function helpWidth(): number;
37
+ /**
38
+ * Render the top-level signpost index. Pure and width-parameterized so the
39
+ * contract test can assert its line budget at a fixed width. Returns the body
40
+ * WITHOUT a trailing newline.
41
+ */
42
+ export declare function renderTopLevelHelp(program: Command, width: number): string;
43
+ /** The valid topic names, in the order the "unknown topic" hint lists them. */
44
+ export declare const TOPIC_NAMES: readonly string[];
45
+ /** Render one topic to `width`, or null when `name` is not a topic. */
46
+ export declare function renderTopic(name: string, width: number): string | null;
47
+ /**
48
+ * Install the custom top-level help and the `help [topic]` command. Replaces
49
+ * the root program's `helpInformation` with the signpost index (so both
50
+ * `things --help` and the help command render it) and disables commander's
51
+ * built-in help command in favor of one that also serves topics.
52
+ */
53
+ export declare function registerHelp(program: Command): void;
54
+ export {};