things-api 0.9.0 → 0.11.0

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

@@ -0,0 +1,152 @@
+import type { ThingsApiConfig } from "../../config.ts";
+import { type UiDriveAux } from "./ui-drag.ts";
+import type { UiPrimitive, UiStep, WriteVector } from "./types.ts";
+/**
+ * Command-level primitives. Extends the recipe `UiPrimitive` set with the
+ * INTERNAL sub-steps composite recipe steps decompose into: a `click-element`
+ * step becomes read-the-frame (`resolve-frame`) + click-at-center
+ * (`click-point`); a `drag-reorder` step becomes snapshot/scroll/drag cycles
+ * (`sidebar-snapshot`, `sidebar-scroll`, `sidebar-drag` — ui-drag.ts). Keeping
+ * every subprocess call behind the injectable `run` seam makes the
+ * orchestration unit-testable without a GUI.
+ */
+export type UiCommandPrimitive = UiPrimitive | "resolve-frame" | "click-point" | "sidebar-snapshot" | "sidebar-scroll" | "sidebar-drag" | "sidebar-held-drag";
+/** A single primitive dispatch — one stable shape per primitive. */
+export interface UiCommand {
+    primitive: UiCommandPrimitive;
+    label: string;
+    /** osascript source (AX primitives); absent for reveal. */
+    script?: string;
+    /** reveal only: the things:/// URL opened to select the target. */
+    url?: string;
+    /** `script` language for the osascript hop; defaults to AppleScript. */
+    lang?: "applescript" | "javascript";
+    /** Structured command parameters (test-inspectable; never dispatched). */
+    meta?: Record<string, unknown>;
+}
+export interface UiRunResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+/**
+ * Low-level dispatch seam. Injectable so the driver's recipe orchestration,
+ * canary, and abort logic are unit-testable WITHOUT ever touching a real GUI
+ * (CLAUDE.md safety rails — the production app is never a valid target).
+ */
+export type UiRunner = (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>;
+/** resolve-element: does the element exist right now? Returns "true"/"false". */
+export declare function axResolveScript(path: string): string;
+/** press: AXPress the element. */
+export declare function axPressScript(path: string): string;
+/**
+ * set-field-value: enter a value into the dialog's numeric text field (interval,
+ * ends-count, start-days-earlier). It FOCUSES the field, selects all, TYPES the
+ * value, and Tabs to commit — because `set value of <field>` writes the field's
+ * displayed text WITHOUT firing the edit, so the app's binding keeps the old
+ * number (the field shows "5" but the rule stays interval 1 — a silent no-op
+ * exactly like `set value` on a pop-up, UIC6; it went unnoticed while every base
+ * case used the default interval 1). Real keystrokes fire the change the binding
+ * needs; Tab (not Return, which would fire the default OK button) commits and
+ * moves focus. Foreground-bound (keystrokes reach the frontmost app) — the
+ * reveal/activate preamble puts Things there. One stable command shape.
+ */
+export declare function axSetValueScript(path: string, value: string): string;
+/**
+ * select-popup: choose an item in a pop-up button by NAME. Setting `value` on a
+ * Things pop-up button is a silent no-op (UIC1 / UI2-i) — the control must be
+ * opened and the menu item clicked. The open-click is POLLED until the menu
+ * actually renders: in the full-vocabulary dialog a preceding pop-up's menu is
+ * still animating closed when the next select fires, and that first open-click
+ * is ABSORBED (the pop-up stays closed, so `menu 1` is an invalid index and the
+ * item click errors -1719, UIC6). Re-clicking only while the menu is absent
+ * (never once it is open) opens it reliably without toggling it back shut. One
+ * stable command shape per primitive.
+ */
+export declare function axSelectPopupScript(path: string, value: string): string;
+/**
+ * select-row: select a PROJECT row by title, purely via AX (UIC4-a). Walks the
+ * content table's rows, issues the row `select` action on each (which REPLACES
+ * the table selection — single-select, UIC5), and reads back Things' `name of
+ * selected to dos`; the first row whose readback equals the target title is LEFT
+ * selected and the script returns "OK". Non-selectable rows (the area/Someday
+ * header, the blank spacer) select nothing (readback count 0) and are skipped.
+ * Returns "NOMATCH" if no row selects to the title — the readback is the
+ * selection-landed verification, so a match guarantees the intended row is
+ * selected. One stable command shape per primitive.
+ *
+ * UIC5 correction: the shipped form set the TABLE's `AXSelectedRows` attribute
+ * to a one-row list, which is a SILENT NO-OP on Things' content table via System
+ * Events (no error, selection never lands). The row `select` action is the
+ * working pure-System-Events route and stays background-capable with no focus
+ * steal (UIC5-e). (UIC4-a proved settability with the ObjC-bridge NSArray set —
+ * a different API than the System Events attribute set the driver shells out to.)
+ */
+export declare function axSelectRowScript(tablePath: string, title: string): string;
+/**
+ * select-heading-row: select a HEADING as a content-table row by POSITION,
+ * purely via AX (HEADCERT1). A heading is not `things:///show`-selectable and
+ * its row carries no stable AX title handle, so identity is positional. Walks
+ * the revealed project view's content table; for each row it issues the row
+ * `select` action, then checks two things: the row genuinely took the selection
+ * (`selected of row` — header/spacer rows do not) AND `Things3 → name of
+ * selected to dos` is EMPTY (a heading is not a to-do; a to-do row's readback is
+ * its title). The Nth such heading row (0-based `ordinal`, in top-to-bottom =
+ * `index` order) is LEFT selected and the script returns "OK"; "NOMATCH" if the
+ * project has fewer headings. With the heading selected, `Items ▸ Convert to
+ * Project…` enables. Pure System Events, background-capable, no focus steal.
+ * One stable command shape per primitive.
+ */
+export declare function axSelectHeadingRowScript(tablePath: string, ordinal: number): string;
+/** activate: foreground Things (the fallback preamble step). */
+export declare function axActivateScript(): string;
+/** key: a space-separated keystroke spec (e.g. "down down return"). */
+export declare function axKeyScript(keys: string): string;
+/** The abort keystroke sent to dismiss a half-open sheet/popover on failure. */
+export declare function axAbortScript(): string;
+/**
+ * resolve-frame: read the element's on-screen frame (top-left origin, points)
+ * from the live AX tree and print "x y w h". Used by `click-element` to target
+ * the frame CENTER — the position comes from AX (`position`/`size`), never a
+ * guessed pixel, so a missing element errors (fail-closed) instead of clicking
+ * a stale coordinate. Points map 1:1 to CGEvent coordinates (NATIVE1-b).
+ */
+export declare function axFrameScript(path: string): string;
+/**
+ * click-point: synthesize a single left mouse click at (x, y) via the global
+ * HID event tap (the NATIVE1 JXA ObjC-bridge path — `CGEventPostToPid` is inert
+ * for Things' hit-testing; only `CGEventPost(kCGHIDEventTap)` lands). The HID
+ * tap posts to the FOREGROUND surface, so the recipe must have activated Things
+ * first. Event types are the stable CGEventType values (5 = mouse-moved,
+ * 1 = left-down, 2 = left-up).
+ */
+export declare function jxaClickScript(x: number, y: number): string;
+/**
+ * set-datetime: set the Repeat dialog's `AXDateTimeArea` (reminder time / "ends
+ * on date" bound) via the ObjC AX bridge. Things' date/time control holds an
+ * NSDate, and System Events cannot write it (`set value … to <date>` → -10000,
+ * UIC6), so — like the mouse-synthesis primitive — this runs in JXA and calls
+ * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly. The control is
+ * found by ROLE within Things' front dialog (there is exactly one during a
+ * reminder/end-date step; the matrix never sets both at once), polled briefly
+ * so it is caught right after the checkbox/pop-up that reveals it, and the
+ * script THROWS when absent so the driver fails closed. `spec` is
+ * `time:HH:mm` (keep the control's date, overwrite the time-of-day) or
+ * `date:YYYY-MM-DD` (overwrite the date at midnight). One stable JXA shape.
+ */
+export declare function axSetDateTimeScript(spec: string): string;
+/** Parse a resolve-frame "x y w h" line into the frame's center point. */
+export declare function parseFrameCenter(stdout: string): {
+    x: number;
+    y: number;
+} | null;
+/** Compile one recipe step into its primitive command (no dispatch). */
+export declare function commandForStep(step: UiStep, targetUuid: string): UiCommand;
+/**
+ * The ui vector. Config-gated: when `ui.enabled` is false the matrix reports
+ * every op unsupported (with a remediation naming the config key + setup doc),
+ * so the operation is never dispatched. When enabled, `execute` runs the
+ * compiled recipe fail-closed.
+ */
+export declare function createUiVector(config: ThingsApiConfig, run?: UiRunner, aux?: UiDriveAux): WriteVector;