things-api 0.16.0 → 0.18.0

package/scripts/deputy-cert-setup.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# One-time ceremony: mint the persistent self-signed code-signing certificate
+# ("things-deputy-signing") that scripts/build-helpers.sh signs the deputy with.
+#
+# WHY A PERSISTENT CERT: macOS attaches Automation/Accessibility/file grants to
+# the responsible process's code signature. A stable certificate means every
+# rebuild of the deputy keeps the same identity — grants survive. Ad-hoc
+# signing mints a fresh identity per build, which silently re-introduces the
+# grant churn the deputy exists to end, so it is deliberately not supported.
+#
+# INTERACTIVE: importing trust settings prompts for your login-keychain
+# password / an authorization dialog. Run this yourself at the machine; it is
+# not for unattended execution. Everything stays in your login keychain —
+# nothing is written to the repository.
+#
+# Re-running is safe: if the identity already exists, the script leaves it be.
+set -euo pipefail
+
+IDENTITY="things-deputy-signing"
+
+if security find-identity -v -p codesigning 2>/dev/null | grep -q "$IDENTITY"; then
+  echo "signing identity '$IDENTITY' already exists — nothing to do."
+  exit 0
+fi
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+cat >"$WORK/ext.cnf" <<'EOF'
+[ req ]
+distinguished_name = dn
+x509_extensions = codesign_ext
+prompt = no
+[ dn ]
+CN = things-deputy-signing
+[ codesign_ext ]
+keyUsage = critical,digitalSignature
+extendedKeyUsage = critical,codeSigning
+basicConstraints = critical,CA:false
+EOF
+
+# 10-year self-signed code-signing cert + key, bundled as a throwaway p12.
+openssl req -x509 -newkey rsa:2048 -sha256 -days 3650 -nodes \
+  -keyout "$WORK/key.pem" -out "$WORK/cert.pem" -config "$WORK/ext.cnf" >/dev/null 2>&1
+openssl pkcs12 -export -inkey "$WORK/key.pem" -in "$WORK/cert.pem" \
+  -name "$IDENTITY" -passout pass:transient -out "$WORK/bundle.p12" >/dev/null 2>&1
+
+echo "importing '$IDENTITY' into the login keychain (codesign is granted access)..."
+security import "$WORK/bundle.p12" -k "$HOME/Library/Keychains/login.keychain-db" \
+  -P transient -T /usr/bin/codesign
+
+echo "marking the certificate trusted for code signing (this may prompt)..."
+security add-trusted-cert -p codeSign \
+  -k "$HOME/Library/Keychains/login.keychain-db" "$WORK/cert.pem"
+
+echo
+echo "done. Next:"
+echo "  bash scripts/build-helpers.sh   # now signs with $IDENTITY"
+echo "  things deputy install          # (re)install the signed helper"
+echo "  things deputy status           # verify signing: signed ($IDENTITY)"

package/skills/things-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: things-cli
 description: Read and manage a user's tasks in the Things 3 app (macOS) through the `things` CLI — list views like Today/Inbox/Upcoming, search, and create, edit, schedule, complete, move, or organize to-dos, projects, areas, headings, and tags. Use whenever the user asks about their tasks, to-dos, projects, or anything in Things.
-version: 0.16.0
+version: 0.18.0
 ---
 
 # Things CLI
@@ -10,7 +10,7 @@ version: 0.16.0
 
 `things --help` is the one-screen index; `things <group> --help` lists a group's verbs and flags (always current for the binary you invoke); `things help <topic>` opens a contract guide — topics: `agent`, `filters`, `ids`, `move`, `output`, `repeating`, `writes`.
 
-**This skill's reference files** are exactly `data-model`, `contracts`, `ordering`, `errors`, `banner`, `gui` (all `references/*.md`) — do not guess other names. Read *shapes* (every view's JSON, `stage`/`when`, the compact/full tiers) live in `data-model`; the envelope, exit codes, undo, batch, and recurrence in `contracts`; move/reorder axes in `ordering`; the error contract in `errors`. There is no `reads`/`writes`/`recurrence`/`safety` file. Most tasks need only this page — open a reference only when a link below sends you there.
+**This skill's reference files** are exactly `data-model`, `contracts`, `repeating`, `ordering`, `errors`, `banner`, `gui` (all `references/*.md`) — do not guess other names. Read *shapes* (every view's JSON, `stage`/`when`, the compact/full tiers) live in `data-model`; the envelope, exit codes, undo, batch, and the recurrence contract in `contracts`; the repeating model, scheduling vocabulary, and deadline law in `repeating`; move/reorder axes in `ordering`; the error contract in `errors`. There is no `reads`/`writes`/`recurrence`/`safety` file. Most tasks need only this page — open a reference only when a link below sends you there.
 
 ## Data model (read this first)
 
@@ -46,6 +46,7 @@ These hold regardless of the binary version; see [references/contracts.md](refer
 - **Exit codes**: `0` landed and checked · `2` usage · `3` verify-failed · `4` blocked · `5` drift-blocked · `6` unsupported · `7` environment (`1` is an internal bug). Nonzero means the change did NOT stick; the message names the fix.
 - **Previews, undo & idempotency**: `--dry-run` is universal — accepted by every command, it guarantees nothing changes: on a read it returns the normal output unchanged, on a write it shows the exact plan without executing; `things undo` reverses recent changes made through this tool (each reversible write returns an `undoToken`); a single mutation may carry `--op-id <key>` so an ambiguous resubmission is recognized as already applied (the variadic `move`/`reorder` refuse it — use `things batch` with a per-line `opId`).
 - **Timeline-silent mutations** (`--preserve-modified`, MCP `preserve_modified`): a universal write flag that keeps a change off the modification-date timeline. Some writes (applying/removing a tag, editing a field, resolving an item) re-stamp each edited item's modification date — the key `things changes --since <moment>` and any watch/sync process sort on. `--preserve-modified` captures each PRE-EXISTING edited item's modification date before the write and restores it (to the whole second) afterward, so the edit does not surface as a new change. It is the enabler for a mass retro-tag or bulk cleanup that must not flood `changes`. A pure create (`add`) is a no-op; the restore is best-effort (a failure is reported per item, the change itself stands) and the result carries `preservedModified: <n>`. **Safe against a synced (Things Cloud) store** — the restored modification date syncs to the other devices and survives the round-trip, so the item stays off the timeline on every device (SYNC2B); the only edge is a genuinely concurrent edit to the same item on another device, which re-dates it via Things Cloud's per-attribute merge (fails safe — the edit resurfaces, never silently hidden).
+- **Completion hints**: a successful `todo complete`/`todo cancel` result carries a `context` object (`data.context` under `--json`) reporting the OPEN work remaining in the to-do's container(s) — `context.project = {uuid, title, remainingOpen}` when it was in a project (heading children included), `context.today = {remainingOpen}` when it was in Today. Use it to notice an emptied container: `remainingOpen: 0` on the project means every open task there is now done, so you might offer to complete the project itself — it only informs, it never auto-acts. Absent when the to-do was in neither.
 - **Preconditions**: referenced containers and tags must already exist — create nested structures outside-in and reuse each returned UUID.
 - If the user requests a JSON reply schema, return exactly that object after the read or checked write.
 
@@ -63,14 +64,21 @@ Namespaced verb families — run `things <group> --help` for the verbs and `thin
 
 **Resolution timestamps** (`--created-at` / `--completed-at`, both to-dos and projects; ISO date or datetime — a bare date is NOON in the effective zone): `add --completed-at <iso> [--created-at <iso>]` creates the item already RESOLVED in the Logbook (the history-import / GTD-migration path); `add --created-at <iso>` alone is born-open with a backdated creation. On an EXISTING item, `update --created-at` rewrites creation (any status); `update --completed-at` rewrites the completion timestamp of an ALREADY-resolved item (a canceled one stays canceled) — an OPEN item is refused, pointing you at `complete --completed-at` (resolve-and-backdate completed) or `cancel --completed-at` (resolve-and-backdate canceled; the "Completed on" stamp applies to canceled items too). Backdating a resolved item can be a multi-leg, non-atomic sequence — the leg list is disclosed in the result and in `--dry-run`. A project `add --completed-at` cannot seed open `--todo` children (a completed-project import needs every child resolved).
 
-**Guarded writes** surface their consequence and require an explicit flag: deleting a NON-EMPTY area needs `--allow-non-empty`, a permanent delete needs `--dangerously-permanent`, and a UI-driving op (e.g. `area reorder`) needs `--dangerously-drive-gui` plus `things config set ui-enabled true`. The full acknowledgment contract is in [references/errors.md](references/errors.md).
+**Guarded writes** surface their consequence and require an explicit flag: deleting a NON-EMPTY area needs `--allow-non-empty`, a permanent delete needs `--dangerously-permanent`, and a UI-driving op (e.g. `area reorder`, `make-repeating`) needs `--dangerously-drive-gui` plus `things config set ui-enabled true`. The full acknowledgment contract is in [references/errors.md](references/errors.md).
+
+**UI-driving ops are slow — allow a generous timeout, and NEVER read a timeout as success.** A `--dangerously-drive-gui` op visibly drives the Things app and can take OVER A MINUTE on a large, syncing database. Give the command a longer-than-normal wrapper timeout — **at least 180s** when your harness allows it (120s is the floor), and pass `--verify-timeout 120000` or more so the app's own budget outlasts the drive. The cardinal rule: **a timeout, EMPTY output, or a silent no-op is NOT a success** — treat it as "outcome unknown". If your own timeout kills the command first you get EMPTY output (not a result, not an error) and the change MAY STILL have landed; if the app's budget is exceeded first you get a structured timeout that says the outcome is uncertain. In BOTH cases, before doing anything else **re-read the item with `things show <uuid>`** (and, on a dev checkout, check the trace under `~/.local/state/things-api/trace/`) to learn what actually happened. **If your harness KILLS long commands** at a cap you cannot raise, pass `--op-id <key>` on the write, let it die, then run **`things op-result <key>`** in a fresh command — it reads the change history the killed process already wrote and reports whether the op landed (`found`), is still-running/died-mid-flight (`intent-only`, outcome UNCERTAIN), or never recorded (`unknown`). **Do NOT fire an identical retry** — repeated blind retries after a timeout or a kill are exactly how you get duplicate or half-configured series (the original item trashed, a wrong template created). If the state is wrong or ambiguous and a re-read does not clarify it, **STOP and file a bug** with the trace rather than retrying. A genuine success always returns a structured JSON result (with `--json`) naming the new/updated uuid; anything else is not a success. The trace can hold real task titles, so never paste it into a public issue.
 
 **Quick skeletons**: `things todo add "T1" "T2" "T3" [shared flags]` creates several to-dos in one call (every shared flag — `--project`/`--area`/`--when`/`--tags`/… — applies to each; `--id-only` prints the new uuids one per line for chaining; one `undoToken` removes the set). To stand up a new project with children, `things project add "<title>" --todo "T1" --todo "T2" …` (repeatable). For richer per-item metadata or cross-item references, use `things batch`.
 
+## The CLI is the only interface — never route around it
+
+Never construct `things:///` URLs, AppleScript (`tell application "Things3" …`), or Shortcuts invocations yourself — for reads or writes. When this skill is installed, the `things` CLI is the sole supported way to touch Things: raw calls bypass its validation, guards, read-back verification, undo/audit records, and session checks, and some raw shapes crash the app or silently do nothing. If the CLI cannot express something you need, or a command refuses or fails in a way that seems wrong, that is a finding, not an obstacle to work around: capture the exact command and its `--json` error (plus `things op-result <op-id>` output where relevant) and report it on the public issue tracker at github.com/mikegreiling/things-api (synthetic repro data only — never the user's real task content), or surface it to your user if you cannot file. A refusal always names its sanctioned override flag when one exists — that acknowledgment system is the only supported escape hatch.
+
 ## Going deeper
 
 - [references/data-model.md](references/data-model.md) — the full data model, `stage`/`when` derivation, the compact/full tiers, view membership, and filters.
 - [references/contracts.md](references/contracts.md) — the JSON envelope, exit codes, safety/undo/idempotency, batch chaining, and recurrence.
+- [references/repeating.md](references/repeating.md) — repeating series in depth: template vs instances, the scheduling vocabulary, off-schedule first occurrences, the deadline law (the anchor names the DUE date), ends bounds, and the GUI-drive operational rules.
 - [references/ordering.md](references/ordering.md) — move vs reorder in depth: axes, gates, caps, automatic fallbacks, placement guarantees, and the one dead class (templates).
 - [references/errors.md](references/errors.md) — the error contract: the candidate shape, dead-row hints, hazard acknowledgments, and the error-code registry.
 - [references/banner.md](references/banner.md) — the Today "new to-dos" banner, the provisional `•` pip, reminder/evening liveness, and what a watcher sees.

package/skills/things-cli/references/errors.md

@@ -55,3 +55,7 @@ Every `error.code` is drawn from a frozen registry. Route on the code, and for t
 | `verify-failed` | A multi-leg move/reorder failed mid-way (`detail.failed`/`completed`). | 3 |
 
 A consumer that does not recognize a specific suffix routes on the prefix (`blocked:` / `verify-failed:`) and the exit code.
+
+## A failure is never a license to bypass the CLI
+
+Whatever the error, do not fall back to hand-built `things:///` URLs, AppleScript, or Shortcuts calls — those bypass the validation, verification, and undo/audit layers this tool exists to provide, and several raw shapes crash the app or fail silently. Refusals that support an override name their acknowledgment flag in the message; that flag system is the only sanctioned escape hatch. Anything else the CLI cannot do is a reportable finding (see the main skill document), not an invitation to improvise.

package/skills/things-cli/references/repeating.md

@@ -0,0 +1,69 @@
+# Repeating series — the model, the scheduling vocabulary, and the deadline law
+
+A repeating item is a **template** plus the **instances** it spawns. The template holds the rule (how often, on what calendar day, with what deadline/reminder/end bound); each occurrence the app materializes is a separate to-do (or project) you complete normally. Completing an instance never touches the template; the template keeps spawning the next occurrence on schedule.
+
+## The verbs
+
+- `things todo make-repeating <ref> --frequency … --interval …` — turn an existing plain to-do into a repeating series. This **REPLACES the item**: the original to-do disappears and a fresh template takes its place, so the uuid you get back is the TEMPLATE's, not the original's. Cannot be undone through the normal path (the original is moved to the Trash; `things undo` removes the new series and restores it).
+- `things todo add-repeating "<title>" --frequency … --interval …` — create a new to-do already repeating, in one step.
+- `things todo reschedule-repeat <ref> --frequency … --interval …` — change the rule of an EXISTING template in place (identity preserved). Only the fields you name change; an unnamed deadline/reminder/anchor is left as it was.
+- `things todo pause-repeat <ref>` / `resume-repeat <ref>` — suspend/restart spawning without losing the rule.
+- `things project …` mirrors all of the above for repeating projects.
+
+All of these drive the Things app's own Repeat dialog, so they require `--dangerously-drive-gui` (and `things config set ui-enabled true`). See the operational rules at the bottom.
+
+## The scheduling vocabulary
+
+- **`--frequency`** `daily | weekly | monthly | yearly`, **`--interval N`** = every N of those units.
+- **`--when <YYYY-MM-DD>`** — the date the FIRST occurrence APPEARS (its start). Later occurrences follow the rule's calendar anchor. If you omit `--when`, `make-repeating` starts from the item's own scheduled date.
+- **The calendar anchor** — WHAT day the series recurs on, per frequency:
+  - weekly → `--weekdays monday,wednesday,friday` (one or more).
+  - monthly → `--on-day <1–31 | last>`, OR an nth-weekday with `--on-weekday <weekday> --on-ordinal <1–5 | last>`.
+  - yearly → `--yearly-month <1–12>` plus `--on-day` (or the nth-weekday pair).
+- **Derived anchor.** If you give `--when` but NO explicit anchor, the anchor is taken FROM `--when` (weekly → its weekday, monthly → its day-of-month, yearly → its month + day). So `make-repeating <ref> --frequency yearly --when 2028-10-16` recurs every October 16 with no anchor flags needed.
+
+## Off-schedule first occurrence (a first-class pattern)
+
+The first occurrence does NOT have to sit on the recurring grid. If `--when` disagrees with an explicit anchor, the series APPEARS on `--when` the first time and follows the anchor from the second occurrence on. Example: `--frequency weekly --weekdays wednesday --when <a Thursday>` = a Thursday first occurrence, then Wednesdays every week after. Weekly and yearly rules support this; the command discloses both halves of the landed pattern (`appears <date>; thereafter <rule>`) in its result and in `--dry-run`.
+
+**One exception — monthly.** A monthly rule cannot start off its anchor day: the app snaps the first occurrence to the anchor's day-of-month, so an off-anchor monthly first is refused up front. Put `--when` on the anchor day, or omit the anchor to take it from `--when`.
+
+## The deadline law (read this before combining `--deadline` with an anchor)
+
+`--deadline` gives each occurrence a due date; `--start-days-earlier N` makes each occurrence APPEAR N days before it is DUE. The key rule: **in deadline mode the calendar anchor names the DUE date, and `--when` is still the APPEAR (start) date.** So an explicit anchor must name `when + N` (the due date), not `--when` itself.
+
+Worked example — intent "appears October 16, due October 30" (a 14-day lead):
+
+- Simplest: `--frequency yearly --when 2028-10-16 --deadline --start-days-earlier 14` with NO anchor flags — the due-date anchor is derived as October 30 and each occurrence appears 14 days earlier, on October 16.
+- Explicit anchor equivalent: name the DUE date — `--yearly-month 10 --on-day 30 --when 2028-10-16 --deadline --start-days-earlier 14`.
+
+If you instead write an explicit anchor on the APPEAR date (`--on-day 16` with the same `--when` and lead), you are asking for an off-schedule first occurrence relative to the due-date anchor — for weekly/yearly this is honored and disclosed (the first occurrence appears/dues on your `--when`, the ongoing series dues on the anchor); a monthly combination of this shape is refused as above. When you want the two to agree, either drop the anchor flags (derived) or set the anchor to the due date (`when + N`).
+
+### Repeating deadlines on `add-repeating`: two spellings for one geometry
+
+A concrete `--deadline <date>` on `todo add-repeating` sets each occurrence's due date relative to its own start, and the RULE owns it: every occurrence is deadlined, the FIRST one due on the date you name. You state that geometry in ONE of two equivalent ways — the tool does the arithmetic:
+
+- **Concrete** — `--deadline <date>` is the first occurrence's due date; the per-occurrence lead is derived as `deadline − --when`. Reach for this when you know both dates.
+- **Relative** — `--start-days-earlier N` names the lead directly (each occurrence starts N days before its own deadline; the first deadline is derived as `--when + N`). Reach for this when the intent is genuinely relative ("due two weeks after it appears").
+
+The steer: state the two dates you actually know, pick the spelling that matches your intent, and **give ONE form or the other, never both** — never compute one from the other yourself. Both need a concrete `--when` (and `--deadline` must be on or after it); the anchor names the DUE date as usual; neither applies to an after-completion series. The safety net: if you do pass both, they must agree (`deadline − --when == N`), and a mismatch is refused up front with a message naming both corrected spellings.
+
+One call, no follow-up `reschedule-repeat`: `todo add-repeating "Taxes" --when 2027-03-15 --deadline 2027-05-31 --frequency yearly --yearly-month 5 --on-weekday monday --on-ordinal last` deadlines every occurrence with a 77-day lead. (A concrete `--deadline` now maps to the rule; historically it landed on the seed only and double-booked the first occurrence — see [docs/lab/dblspawn1-preserved-instance.md](../../../docs/lab/dblspawn1-preserved-instance.md).)
+
+## Ends bounds, reminder, and limits worth knowing
+
+- **Ends bound** (default: never): `--ends-after N` stops after N total occurrences (the ORIGINAL count, not a remaining tally — it does not tick down), or `--ends-on <date>` stops after that date. An exhausted series reads as `ended`.
+- **Reminder**: `--reminder HH:mm` sets a time-of-day alert on each occurrence.
+- **After-completion cadence**: `--after-completion` repeats N units AFTER each occurrence is completed, rather than on a fixed calendar. It has NO calendar anchor and takes NO end bound — those are refused.
+- **Expressibility**: a rule can carry only ONE end bound (not both a date and a count), and a monthly/yearly rule only ONE calendar anchor. Reschedule cannot restore a rule shape the Repeat dialog itself cannot produce.
+
+## Operational rules for the GUI-driven repeat commands
+
+These commands visibly drive the Things app and are slow — often OVER A MINUTE on a large, syncing database. (This is the same guidance as the main skill page and `things help repeating`, condensed.)
+
+- Allow a generous wrapper timeout — **at least 180s** where your harness permits (120s floor) — and pass `--verify-timeout 120000` or more so the app's own budget outlasts the drive.
+- **A timeout, empty output, or a silent no-op is NOT success** — treat it as "outcome unknown". Before doing anything else, re-read the item with `things show <ref>` (and, on a dev checkout, the trace under `~/.local/state/things-api/trace/`) to learn what actually landed.
+- **If your environment kills long commands** (a hard wall-time cap you cannot raise): pass `--op-id <key>` on the write, let the command die, then run **`things op-result <key>`** in a fresh command to read what actually happened — it reads the local change history the killed process already wrote and reports `found` (the final result + target), `intent-only` (started but no outcome recorded — still running or the process died mid-flight, outcome UNCERTAIN), or `unknown`. This is the recovery path for a capped harness; do NOT infer the outcome from the kill. (`--op-id` works on the single-op repeat verbs like `reschedule-repeat`; `make-repeating` / `add-repeating` are compounds — express them as a `batch` line with a per-line `opId` if you need this.)
+- **Never fire an identical retry** after a timeout or a kill — a blind retry is how you get a duplicate or half-configured series (original trashed, wrong template created). Learn the real outcome first (`things op-result` / `things show`); if the state is wrong or ambiguous, STOP and file a bug with the trace.
+- These ops need Things reachable on the current desktop (not a locked screen or a covering full-screen app); a session it cannot reach is refused cleanly with a remediation, touching nothing.
+- A genuine success always returns a structured JSON result (with `--json`) naming the new/updated uuid.