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.
- package/README.md +31 -11
- package/dist/audit/log.js +56 -2
- package/dist/audit/log.js.map +1 -1
- package/dist/audit/schema.d.ts +26 -8
- package/dist/audit/schema.js +42 -1
- package/dist/audit/schema.js.map +1 -1
- package/dist/cli/commands/area.d.ts +34 -2
- package/dist/cli/commands/area.js +140 -28
- package/dist/cli/commands/area.js.map +1 -1
- package/dist/cli/commands/doctor.d.ts +1 -1
- package/dist/cli/commands/doctor.js +44 -5
- package/dist/cli/commands/doctor.js.map +1 -1
- package/dist/cli/commands/mcp.js +23 -4
- package/dist/cli/commands/mcp.js.map +1 -1
- package/dist/cli/commands/project.d.ts +23 -1
- package/dist/cli/commands/project.js +82 -15
- package/dist/cli/commands/project.js.map +1 -1
- package/dist/cli/commands/reads.d.ts +6 -125
- package/dist/cli/commands/reads.js +649 -657
- package/dist/cli/commands/reads.js.map +1 -1
- package/dist/cli/commands/repeat-flags.d.ts +20 -0
- package/dist/cli/commands/repeat-flags.js +76 -0
- package/dist/cli/commands/repeat-flags.js.map +1 -0
- package/dist/cli/commands/setup.js +2 -3
- package/dist/cli/commands/setup.js.map +1 -1
- package/dist/cli/commands/show.d.ts +1 -1
- package/dist/cli/commands/show.js +169 -18
- package/dist/cli/commands/show.js.map +1 -1
- package/dist/cli/commands/snapshot.js +1 -1
- package/dist/cli/commands/snapshot.js.map +1 -1
- package/dist/cli/commands/todo.d.ts +1 -1
- package/dist/cli/commands/todo.js +21 -9
- package/dist/cli/commands/todo.js.map +1 -1
- package/dist/cli/commands/writes.js +378 -148
- package/dist/cli/commands/writes.js.map +1 -1
- package/dist/cli/did-you-mean.d.ts +29 -0
- package/dist/cli/did-you-mean.js +53 -0
- package/dist/cli/did-you-mean.js.map +1 -0
- package/dist/cli/excess-args.d.ts +15 -0
- package/dist/cli/excess-args.js +51 -0
- package/dist/cli/excess-args.js.map +1 -0
- package/dist/cli/glyphs.d.ts +67 -7
- package/dist/cli/glyphs.js +202 -19
- package/dist/cli/glyphs.js.map +1 -1
- package/dist/cli/help.d.ts +54 -0
- package/dist/cli/help.js +355 -0
- package/dist/cli/help.js.map +1 -0
- package/dist/cli/main.js +36 -21
- package/dist/cli/main.js.map +1 -1
- package/dist/cli/period.d.ts +39 -0
- package/dist/cli/period.js +141 -0
- package/dist/cli/period.js.map +1 -0
- package/dist/cli/read-driver.d.ts +83 -0
- package/dist/cli/read-driver.js +215 -0
- package/dist/cli/read-driver.js.map +1 -0
- package/dist/cli/render.d.ts +246 -0
- package/dist/cli/render.js +806 -0
- package/dist/cli/render.js.map +1 -0
- package/dist/cli/resolve-invocation.d.ts +116 -0
- package/dist/cli/resolve-invocation.js +261 -0
- package/dist/cli/resolve-invocation.js.map +1 -0
- package/dist/cli/shell-quote.d.ts +9 -0
- package/dist/cli/shell-quote.js +12 -0
- package/dist/cli/shell-quote.js.map +1 -0
- package/dist/cli/tag-filters.d.ts +59 -0
- package/dist/cli/tag-filters.js +57 -0
- package/dist/cli/tag-filters.js.map +1 -0
- package/dist/cli/verb-hint.d.ts +25 -0
- package/dist/cli/verb-hint.js +138 -0
- package/dist/cli/verb-hint.js.map +1 -0
- package/dist/cli/width.d.ts +135 -0
- package/dist/cli/width.js +313 -0
- package/dist/cli/width.js.map +1 -0
- package/dist/client.d.ts +146 -24
- package/dist/client.js +106 -16
- package/dist/client.js.map +1 -1
- package/dist/config.d.ts +11 -0
- package/dist/config.js +3 -0
- package/dist/config.js.map +1 -1
- package/dist/contracts.d.ts +136 -1
- package/dist/contracts.js +44 -1
- package/dist/contracts.js.map +1 -1
- package/dist/db/fingerprint.d.ts +12 -0
- package/dist/db/fingerprint.js +15 -1
- package/dist/db/fingerprint.js.map +1 -1
- package/dist/db/locate.js +1 -1
- package/dist/db/locate.js.map +1 -1
- package/dist/diagnose.d.ts +63 -0
- package/dist/diagnose.js +38 -1
- package/dist/diagnose.js.map +1 -1
- package/dist/index.d.ts +30 -4
- package/dist/index.js +35 -2
- package/dist/index.js.map +1 -1
- package/dist/mcp/server.d.ts +9 -1
- package/dist/mcp/server.js +850 -128
- package/dist/mcp/server.js.map +1 -1
- package/dist/model/entities.d.ts +40 -7
- package/dist/model/entities.js.map +1 -1
- package/dist/model/mappers.d.ts +7 -0
- package/dist/model/mappers.js +20 -3
- package/dist/model/mappers.js.map +1 -1
- package/dist/model/occurrences.d.ts +6 -1
- package/dist/model/occurrences.js +9 -5
- package/dist/model/occurrences.js.map +1 -1
- package/dist/model/recurrence.d.ts +17 -8
- package/dist/model/recurrence.js.map +1 -1
- package/dist/model/serialize.d.ts +28 -0
- package/dist/model/serialize.js +80 -0
- package/dist/model/serialize.js.map +1 -0
- package/dist/model/when-sugar.d.ts +47 -0
- package/dist/model/when-sugar.js +45 -0
- package/dist/model/when-sugar.js.map +1 -0
- package/dist/read/area-view.d.ts +8 -1
- package/dist/read/area-view.js +49 -13
- package/dist/read/area-view.js.map +1 -1
- package/dist/read/caps.d.ts +14 -0
- package/dist/read/caps.js +21 -0
- package/dist/read/caps.js.map +1 -0
- package/dist/read/filter-contract.d.ts +117 -0
- package/dist/read/filter-contract.js +78 -0
- package/dist/read/filter-contract.js.map +1 -0
- package/dist/read/log-boundary.d.ts +9 -4
- package/dist/read/log-boundary.js.map +1 -1
- package/dist/read/predicates.d.ts +61 -0
- package/dist/read/predicates.js +78 -0
- package/dist/read/predicates.js.map +1 -0
- package/dist/read/project-view.d.ts +12 -1
- package/dist/read/project-view.js +39 -8
- package/dist/read/project-view.js.map +1 -1
- package/dist/read/queries.d.ts +156 -8
- package/dist/read/queries.js +261 -38
- package/dist/read/queries.js.map +1 -1
- package/dist/read/search-rank.d.ts +36 -0
- package/dist/read/search-rank.js +31 -0
- package/dist/read/search-rank.js.map +1 -0
- package/dist/read/sections.d.ts +51 -0
- package/dist/read/sections.js +37 -0
- package/dist/read/sections.js.map +1 -0
- package/dist/read/show-target.d.ts +13 -4
- package/dist/read/show-target.js +11 -2
- package/dist/read/show-target.js.map +1 -1
- package/dist/read/sidebar-order.d.ts +19 -0
- package/dist/read/sidebar-order.js +93 -0
- package/dist/read/sidebar-order.js.map +1 -0
- package/dist/read/tags.d.ts +27 -3
- package/dist/read/tags.js +83 -12
- package/dist/read/tags.js.map +1 -1
- package/dist/read/truncation.d.ts +71 -0
- package/dist/read/truncation.js +217 -0
- package/dist/read/truncation.js.map +1 -0
- package/dist/read/views.d.ts +177 -19
- package/dist/read/views.js +390 -213
- package/dist/read/views.js.map +1 -1
- package/dist/surface-copy.d.ts +42 -0
- package/dist/surface-copy.js +55 -0
- package/dist/surface-copy.js.map +1 -1
- package/dist/sync-health.d.ts +78 -0
- package/dist/sync-health.js +312 -0
- package/dist/sync-health.js.map +1 -0
- package/dist/write/accessibility-probe.d.ts +12 -0
- package/dist/write/accessibility-probe.js +63 -0
- package/dist/write/accessibility-probe.js.map +1 -0
- package/dist/write/automation-probe.d.ts +7 -0
- package/dist/write/automation-probe.js +8 -1
- package/dist/write/automation-probe.js.map +1 -1
- package/dist/write/batch.js +4 -2
- package/dist/write/batch.js.map +1 -1
- package/dist/write/capabilities.d.ts +8 -0
- package/dist/write/capabilities.js +13 -5
- package/dist/write/capabilities.js.map +1 -1
- package/dist/write/commands.d.ts +2 -0
- package/dist/write/commands.js +562 -48
- package/dist/write/commands.js.map +1 -1
- package/dist/write/edit-checklist.js +3 -2
- package/dist/write/edit-checklist.js.map +1 -1
- package/dist/write/guards.d.ts +2 -7
- package/dist/write/guards.js +64 -6
- package/dist/write/guards.js.map +1 -1
- package/dist/write/heading.js +2 -0
- package/dist/write/heading.js.map +1 -1
- package/dist/write/lock.d.ts +40 -2
- package/dist/write/lock.js +91 -14
- package/dist/write/lock.js.map +1 -1
- package/dist/write/make-repeating-project.d.ts +4 -0
- package/dist/write/make-repeating-project.js +253 -0
- package/dist/write/make-repeating-project.js.map +1 -0
- package/dist/write/operations.d.ts +145 -1
- package/dist/write/operations.js +48 -0
- package/dist/write/operations.js.map +1 -1
- package/dist/write/pipeline.d.ts +19 -0
- package/dist/write/pipeline.js +109 -26
- package/dist/write/pipeline.js.map +1 -1
- package/dist/write/pre-state.d.ts +68 -3
- package/dist/write/pre-state.js +102 -3
- package/dist/write/pre-state.js.map +1 -1
- package/dist/write/reopen.js +3 -2
- package/dist/write/reopen.js.map +1 -1
- package/dist/write/reorder.js +27 -17
- package/dist/write/reorder.js.map +1 -1
- package/dist/write/repeat-rule.d.ts +22 -0
- package/dist/write/repeat-rule.js +258 -0
- package/dist/write/repeat-rule.js.map +1 -0
- package/dist/write/reversibility.js +49 -0
- package/dist/write/reversibility.js.map +1 -1
- package/dist/write/tag-refs.d.ts +47 -0
- package/dist/write/tag-refs.js +126 -0
- package/dist/write/tag-refs.js.map +1 -0
- package/dist/write/undo.d.ts +74 -5
- package/dist/write/undo.js +494 -80
- package/dist/write/undo.js.map +1 -1
- package/dist/write/vectors/registry.d.ts +17 -1
- package/dist/write/vectors/registry.js +18 -2
- package/dist/write/vectors/registry.js.map +1 -1
- package/dist/write/vectors/types.d.ts +119 -3
- package/dist/write/vectors/ui-certification.d.ts +48 -0
- package/dist/write/vectors/ui-certification.js +46 -0
- package/dist/write/vectors/ui-certification.js.map +1 -0
- package/dist/write/vectors/ui-drag.d.ts +188 -0
- package/dist/write/vectors/ui-drag.js +1095 -0
- package/dist/write/vectors/ui-drag.js.map +1 -0
- package/dist/write/vectors/ui-recipes.d.ts +70 -0
- package/dist/write/vectors/ui-recipes.js +558 -0
- package/dist/write/vectors/ui-recipes.js.map +1 -0
- package/dist/write/vectors/ui.d.ts +137 -0
- package/dist/write/vectors/ui.js +656 -0
- package/dist/write/vectors/ui.js.map +1 -0
- package/dist/write/verify/delta.d.ts +31 -3
- package/dist/write/verify/delta.js +22 -6
- package/dist/write/verify/delta.js.map +1 -1
- package/dist/write/verify/poller.js +1 -0
- package/dist/write/verify/poller.js.map +1 -1
- package/package.json +1 -1
- package/dist/cli/exit-codes.d.ts +0 -26
- package/dist/cli/exit-codes.js +0 -26
- package/dist/cli/exit-codes.js.map +0 -1
- package/dist/cli/output.d.ts +0 -42
- package/dist/cli/output.js +0 -16
- package/dist/cli/output.js.map +0 -1
package/dist/cli/glyphs.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
88
|
-
|
|
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"}
|
|
142
|
+
: `${-diff} day${diff === -1 ? "" : "s"} overdue`;
|
|
95
143
|
}
|
|
96
144
|
/**
|
|
97
|
-
* Detail-card deadline line value (
|
|
98
|
-
*
|
|
99
|
-
*
|
|
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
|
|
103
|
-
|
|
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
|
-
|
|
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
|
package/dist/cli/glyphs.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../src/cli/glyphs.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;
|
|
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 {};
|