things-api 0.16.0 → 0.18.0

package/dist/write/vectors/types.d.ts

@@ -4,6 +4,7 @@
  * the lab (url-scheme.matrix / applescript.matrix), never hardcoded logic.
  */
 import type { DisruptionTier } from "../../config.ts";
+import type { HazardId } from "../guards.ts";
 import type { OperationKind } from "../operations.ts";
 export type VectorId = "url-scheme" | "applescript" | "shortcuts" | "ui";
 export interface CompiledInvocation {
@@ -46,6 +47,18 @@ export interface UiRecipe {
     /** The item the recipe acts on (revealed/selected via things:///show?id=). */
     targetUuid: string;
     steps: UiStep[];
+    /**
+     * DIALOG-class recipe: it opens a SHEET on the main Things window (the Repeat
+     * editor, the Convert confirm, the Move picker) and waits for it through the
+     * Accessibility tree. Such a recipe needs a Things window that is AX-reachable
+     * on the current Space — on a locked screen or in a full-screen app's Space
+     * the sheet opens on an unreachable window and the wait times out (SESSGATE,
+     * #480). The driver runs a session-reachability probe after the reveal and
+     * refuses (`blocked`) when the window is unreachable. Menu-only recipes (todo
+     * pause/resume — a pure menu-item press that works even under lock, AXVM1) do
+     * NOT set this and are never gated.
+     */
+    needsWindowReachability?: boolean;
 }
 export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-value" | "select-popup" | "wait" | "key"
 /**
@@ -94,17 +107,84 @@ export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-val
  */
  | "select-heading-row"
 /**
- * Set the Repeat dialog's date/time control (the reminder time, the "ends on
- * date" bound) — an `AXDateTimeArea` whose value is an NSDate, NOT a text
- * field (UIC6). System Events cannot set it (`set value … to <date>` errors
- * -10000), so the driver sets `AXValue` to an NSDate through the ObjC bridge
- * (JXA), the same bridge the mouse-synthesis primitive rides. `value` is the
- * spec: `time:HH:mm` (keep the control's date, set the time-of-day, for the
- * reminder) or `date:YYYY-MM-DD` (set the calendar date, for the end bound).
- * The control is located by role within the open dialog and fails closed if
- * it is absent.
+ * Assert the reveal actually landed an ELIGIBLE selection before a menu press
+ * (ADR1, issue #480). A `things:///show?id=<uuid>` reveal is assumed to select
+ * the to-do row, but on some surfaces (a future-scheduled to-do in Upcoming, an
+ * area view) it may navigate without leaving the row selected — and an AXPress
+ * on the resulting DISABLED `Items ▸ Repeat…` "succeeds" as a silent no-op, so
+ * the dialog never opens and the drive dies at the dialog-wait timeout with no
+ * hint of the real cause. This step closes that gap fail-closed: it reads back
+ * `Things3 → id of selected to dos` and requires EXACTLY the target uuid to be
+ * selected, then reads the addressed menu item's `AXEnabled`. It returns "OK"
+ * only when the target is the sole selection AND the menu item is enabled;
+ * otherwise it returns a diagnostic (`NOTSEL…`/`WRONGSEL…`/`DISABLED…`) the
+ * driver surfaces as an EARLY, named failure. `value` is the target uuid; `path`
+ * the menu item to enabled-check. Pure System Events, background-capable.
+ */
+ | "assert-eligible"
+/**
+ * Set one of the Repeat dialog's date/time controls — each an `AXDateTimeArea`
+ * whose value is an NSDate, NOT a text field (UIC6). System Events cannot set
+ * it (`set value … to <date>` errors -10000), so the driver sets `AXValue` to
+ * an NSDate through the ObjC bridge (JXA), the same bridge the mouse-synthesis
+ * primitive rides. `value` is the spec: `time:HH:mm` (keep the control's date,
+ * set the time-of-day) or `date:YYYY-MM-DD` (set the calendar date).
+ *
+ * A fixed rule can expose up to THREE date areas at once — "Next:" (the first
+ * occurrence), the "Ends: on date" bound, and the reminder time (ANCH2 census,
+ * docs/lab/anch2-next-field.md) — so the target is chosen DETERMINISTICALLY by
+ * {@link UiStep.dtTarget}, never "the first AXDateTimeArea by role" (that
+ * ambiguity was the §8v collapse + the UIC6-g reminder mis-verdict). The
+ * reminder is the only time-bearing area; among the midnight date pickers the
+ * "Next" field is the top row and the "Ends" field the bottom row. Fails
+ * closed if the addressed control is absent.
+ */
+ | "set-datetime"
+/**
+ * Converge a dialog CHECKBOX to a target state via a deterministic closed loop
+ * (RRD1): read the checkbox's `AXValue` (0/1), press ONLY when the observed
+ * state differs from the requested {@link UiStep.checkboxTarget}, then re-read to
+ * confirm it landed — never a blind toggle. This is what makes the Repeat
+ * dialog's "Add deadlines" / "Add reminders" checkboxes safe on a PRE-POPULATED
+ * reschedule dialog: the dialog opens with the item's CURRENT deadline/reminder
+ * state already reflected, so an unconditional press flips an already-correct box
+ * the wrong way (the live bug — a blind "Add deadlines" press UNCHECKED an
+ * already-deadlined rule, hiding the "start N days earlier" field it had already
+ * revealed). Only fields the caller actually requested emit a step; an
+ * unspecified `--deadline` / `--reminder` on reschedule emits NO step, so the
+ * pre-populated state is PRESERVED (requested-fields-only law, #492). Fails
+ * closed (an `error` the pipeline re-verifies) if the box will not converge
+ * within the bounded retries.
+ */
+ | "ensure-checkbox"
+/**
+ * MEASURE which shape the open Repeat dialog is (RDLG2) and remember it for
+ * the rest of the drive. Emitted right before the first shape-dependent step;
+ * a dialog matching neither known shape aborts the drive fail-closed rather
+ * than press structural indexes it cannot vouch for.
+ */
+ | "probe-dialog-shape"
+/**
+ * Choose the first occurrence from the Things 3.23 `Next:` pop-up — a bounded
+ * MENU of `Today` plus the rule's own upcoming occurrences (cascading through
+ * `More…` submenus), not a date field (RDLG2). The driver matches the request
+ * against each item's parsed date, descends the cascade, clicks the match, and
+ * reads the pop-up back. A date the rule never produces is UNREACHABLE in this
+ * dialog and fails closed — 3.23 replaced the free-form first-occurrence field
+ * the ≤3.22 `set-datetime next` drive wrote.
  */
- | "set-datetime";
+ | "select-next-occurrence"
+/**
+ * Converge the weekly dialog's weekday ROWS onto an exact target set through a
+ * deterministic closed loop (RDLG2, the RRD1 fix): read the live row count,
+ * press the row-add button until there are at least as many rows as target
+ * weekdays, assign EVERY row from the target set (cycling, so a surplus row
+ * duplicates a target weekday instead of keeping a stale one — the app stores
+ * the weekdays as a set), then read every row back and confirm the set matches.
+ * Replaces the blind first-row-then-"+" drive, which left a pre-populated
+ * dialog's stale weekdays in the committed rule.
+ */
+ | "converge-weekdays";
 export interface UiStep {
     primitive: UiPrimitive;
     /** Human-readable step label — surfaced in the partial-state report. */
@@ -173,7 +253,58 @@ export interface UiStep {
     activateFallback?: boolean;
     /** drag-reorder only: the sidebar move the drag driver performs. */
     drag?: import("./ui-drag.ts").SidebarDragSpec;
+    /**
+     * set-datetime only: WHICH of the dialog's date areas to drive (ANCH2). The
+     * driver selects deterministically — `reminder` = the only time-bearing area;
+     * `next` = the top (smaller-y) midnight date picker; `ends` = the bottom
+     * (larger-y) midnight date picker. Required for every set-datetime step.
+     */
+    dtTarget?: "next" | "ends" | "reminder";
+    /**
+     * ensure-checkbox only: the desired checkbox state. The driver reads the
+     * control's `AXValue` and presses ONLY when it differs from this target, then
+     * confirms convergence (RRD1 closed loop). Required for every ensure-checkbox step.
+     */
+    checkboxTarget?: boolean;
+    /**
+     * Run this step ONLY under the named Repeat-dialog shape (RDLG2). The two
+     * shapes present the FIRST-OCCURRENCE control as different element CLASSES —
+     * an `AXDateTimeArea` (legacy) versus an `AXPopUpButton` (next-popup) — so the
+     * recipe emits BOTH drives and the driver executes the one matching the shape
+     * its `probe-dialog-shape` step measured. A step carrying this field with no
+     * shape probed fails closed.
+     */
+    onlyShape?: RepeatDialogShape;
+    /**
+     * Per-shape overrides merged into the step once the dialog shape is probed
+     * (RDLG2). The 3.23 `Next:` pop-up sits between Ends and every per-frequency
+     * control, shifting their group indices by +1 — so the SAME step carries both
+     * index sets and the driver picks by measured structure, never by app version.
+     * A step carrying this field whose probed shape has no entry fails closed.
+     */
+    shaped?: Partial<Record<RepeatDialogShape, {
+        pathCandidates?: string[];
+        value?: string;
+    }>>;
 }
+/**
+ * The structural SHAPE of the Repeat dialog, MEASURED live (never sniffed from
+ * the app version — a version string says nothing about the tree the driver has
+ * to address, and a point release can move either way):
+ *
+ * - `next-popup` — Things 3.23+: the first occurrence is an `AXPopUpButton`
+ *   listing Today + the rule's own upcoming occurrences; it sits between Ends and
+ *   the per-frequency controls, so those are at +1.
+ * - `legacy` — Things ≤ 3.22: the first occurrence is a free-form
+ *   `AXDateTimeArea` and the per-frequency controls follow Ends directly.
+ *
+ * Both shapes label that row `Next:` (measured on 3.22.14 and 3.23 alike), so the
+ * probe discriminates on the CONTROL CLASS occupying the row, not the label.
+ *
+ * Anything matching NEITHER shape is a third, unknown dialog — the drive
+ * refuses rather than press indexes it cannot vouch for.
+ */
+export type RepeatDialogShape = "next-popup" | "legacy";
 export interface VectorSupport {
     support: "yes" | "partial" | "no";
     /**
@@ -200,11 +331,53 @@ export interface ExecuteResult {
     stderr: string;
     /** The transport was killed by its own deadline — the signature of an unanswered consent dialog. */
     timedOut?: boolean;
+    /**
+     * The vector REFUSED at runtime BEFORE touching the app — a precondition it
+     * can only check live (the ui vector's session-reachability gate: a locked
+     * screen / full-screen Space leaves no AX-reachable Things window for the
+     * dialog, SESSGATE #480). The pipeline maps this to a `blocked` outcome
+     * (exit 4), never a transport failure — nothing was mutated.
+     */
+    blocked?: {
+        hazard: HazardId;
+        detail: string;
+        remediation: string;
+    };
+    /**
+     * The ui vector's overall-drive WATCHDOG fired: the drive exceeded its budget
+     * so the CLI — not the caller — gave up first, cleared any open dialog, and
+     * returned (TRACE1, #487). Carried alongside a nonzero `exitCode` + `timedOut`
+     * so the pipeline routes it through the existing transport-failure re-verify
+     * (a mid-commit OK may still have landed), then shapes an HONEST timeout:
+     * confirmed-landed → ok with a disclosure; not-confirmed → verify-failed with
+     * `uncertain` set and the trace path, since a drive aborted mid-commit cannot
+     * promise the app is untouched. See {@link drive}.
+     */
+    watchdog?: {
+        budgetMs: number;
+        elapsedMs: number;
+        /** The step the drive was about to run (or running) when the budget blew. */
+        lastStep: string;
+        /** How the open dialog was cleaned up (SESSGATE clearDialog outcome). */
+        clear: "dismissed" | "cleared-blind" | "may-remain";
+        /** The local trace file reconstructing the timeline, when tracing is on. */
+        tracePath?: string | null;
+    };
 }
 export interface WriteVector {
     id: VectorId;
     matrix: VectorMatrix;
     execute(invocation: CompiledInvocation): Promise<ExecuteResult>;
+    /**
+     * ui vector ONLY: probe whether a Things window is AX-reachable on the current
+     * Space, so a promote ORCHESTRATOR can gate BEFORE it seeds a row (SESSGATE
+     * #480). It returns a not-reachable verdict scoped "session" (locked screen /
+     * full-screen — the certain-failure case the orchestrator refuses on, zero
+     * mutation) or "window" (only Things' window is off-Space — the orchestrator
+     * proceeds; the in-drive gate relocates it). Absent on the real transport
+     * vectors and the simulator, so a caller with no ui vector simply skips the gate.
+     */
+    probeReachability?: () => Promise<import("./session-reachability.ts").ReachabilityVerdict>;
     /**
      * The bench-harness SIMULATOR vector (src/write/vectors/simulator.ts). It
      * presents under a real {@link VectorId} but applies mutations via SQL from

package/dist/write/vectors/ui-recipes.d.ts

@@ -38,6 +38,14 @@ export interface RepeatDialogRule {
     reminder?: string;
     deadline?: boolean;
     startDaysEarlier?: number;
+    /**
+     * The requested FIRST occurrence (ISO `YYYY-MM-DD`), driven into the dialog's
+     * "Next:" date field (ANCH2, issue #476). The default value of Next is the
+     * app's today-anchored first match; overwriting it makes the series start on
+     * the requested date verbatim (subsequent occurrences follow the rule). Omit
+     * to accept the app default. Not applicable to after-completion (no calendar).
+     */
+    next?: string;
 }
 export declare function pauseRepeatRecipe(targetUuid: string): UiRecipe;
 export declare function resumeRepeatRecipe(targetUuid: string): UiRecipe;