things-api 0.19.4 → 0.20.1

package/dist/rescue.d.ts

@@ -0,0 +1,247 @@
+/**
+ * `things rescue` — the headless emergency surface for un-sticking Things
+ * (issue #640).
+ *
+ * WHY THIS EXISTS. Things can reach a state where the app is up, answering, and
+ * unusable to automation, with no scripted way back. Three measured behaviours
+ * converge on it:
+ *
+ *   - a standing modal sheet EMPTIES the app's top-level AppleScript collections
+ *     (oddities §25 / MODALX1), so `delete` reports `-1728 Can't get to do id` on
+ *     a row the database holds open — issue #620's "ghost clone", which has no
+ *     second cause;
+ *   - a standing sheet GATES Things Cloud sync entirely (oddities §24), so writes
+ *     land locally and silently never leave the Mac;
+ *   - a Repeat dialog opened while Things is BACKGROUNDED becomes a detached
+ *     window that nothing dismisses (oddities §26 / DRVLAT1 §5) — not its own
+ *     Cancel, not Escape, not ⌘W, not a real HID click at its Cancel frame.
+ *
+ * The shipped driver never creates the third state (every dialog recipe
+ * activates Things first, which is exactly why that step is permanent), but a
+ * killed client, a harness tool-timeout or a person walking away mid-dialog can
+ * all leave the first two. {@link rescueStatus} reports them; the other two
+ * verbs act on them. This is the single home for both halves — the read-only
+ * census that was once the top-level `ui-state` command lives here now.
+ *
+ * THE THREE VERBS, separated by what they can cost you:
+ *
+ *   - {@link rescueStatus}   free, ungated, read-only — the census + the lock
+ *                            table + a "we must not touch that" verdict;
+ *   - {@link rescueDismiss}  gated two ways — presses ONE dialog's own Cancel;
+ *   - {@link rescueRelaunch} gated two ways — ends the process and starts it
+ *                            again, the only cure measured for oddities §26.
+ *
+ * PERMISSIONS DOCTRINE. Nothing here raises a macOS consent dialog. The screen
+ * is read behind the prompt-free capability verdict, exactly as `doctor
+ * --ui-state` reads it, and a machine that has not granted the access is TOLD so
+ * rather than
+ * prompted. {@link rescueRelaunch} is the deliberate exception to needing that
+ * grant at all — see its own note.
+ */
+import { type AuditWriter } from "./audit/log.ts";
+import { type UiCapability } from "./capability.ts";
+import { type UiState } from "./write/vectors/ui-state.ts";
+import { type UiRunner } from "./write/vectors/ui.ts";
+/** What a relaunch could establish about the database it left behind. */
+export interface RescueSchemaVerdict {
+    /** Did the database open and read as a shape this build understands? */
+    ok: boolean;
+    /** One sentence, for the report. */
+    detail: string;
+}
+/**
+ * Every side-effecting thing this module does, injectable. Production defaults
+ * are the real ones; the unit suite substitutes all of them, which is what makes
+ * the gating, the refusals and the kill ladder testable without an app.
+ */
+export interface RescueDeps {
+    /** The prompt-free GUI capability verdict. */
+    uiCapability?: () => UiCapability;
+    /** The osascript / reveal dispatch seam — the same transport the drive uses. */
+    run?: UiRunner;
+    /** Process environment, for config, the lock path and the change-history directory. */
+    env?: NodeJS.ProcessEnv;
+    /** Where a rescue ACTION records what it did. */
+    audit?: AuditWriter;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    /** Which pids Things is running as, newest first; empty when it is not running. */
+    thingsPids?: () => Promise<number[]>;
+    /** Signal one pid. Never throws for a pid that has already gone. */
+    signal?: (pid: number, sig: NodeJS.Signals) => void;
+    /** Start Things in the BACKGROUND — we do not steal the screen to fix the screen. */
+    launch?: () => Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** Read the database's own verdict, for the post-relaunch check. */
+    schemaStatus?: () => RescueSchemaVerdict;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * A modal that is NOT ours. `inspectable: false` is the signature of a secure
+ * system modal — a macOS privacy/consent dialog, which belongs to no
+ * application's Accessibility tree and which no rescue verb may ever press a
+ * button on. It is reported so the operator knows to look at the screen, and so
+ * they know the refusal that follows is deliberate rather than a failure.
+ */
+export interface RescueForeignModal {
+    /** The application that owns the screen, or null when even that could not be read. */
+    owner: string | null;
+    detail: string;
+}
+/** The mutation lock, as `rescue status` reports it. Read-only, always. */
+export interface RescueLockView {
+    path: string;
+    held: boolean;
+    pid: number | null;
+    /** ISO instant the holder took it. */
+    since: string | null;
+    /** Human age ("4m 12s"), or null when it could not be computed. */
+    heldFor: string | null;
+    /** Does a process with that pid still exist? */
+    alive: boolean;
+    /** Alive AND older than any change takes — old enough to say so. */
+    suspect: boolean;
+    detail: string;
+}
+export interface RescueStatusReport {
+    /** Could the screen be read at all on this machine? */
+    screenReadable: boolean;
+    /** One sentence: the census summary, or the reason there is none. */
+    detail: string;
+    /** The census; null when it could not be read. */
+    state: UiState | null;
+    lock: RescueLockView;
+    /** Set when something we must not touch owns the screen. */
+    foreignModal: RescueForeignModal | null;
+    /** Consequences worth stating — the open-dialog sync gate. */
+    warnings: string[];
+    /** What to do next, including which rescue verb applies. */
+    remediation: string[];
+}
+/**
+ * Read everything a stuck machine can be asked about, without touching any of
+ * it. Never throws and never refuses: the cases this exists for are exactly the
+ * ones where something is already wrong, so every failure is a REPORTED state.
+ */
+export declare function rescueStatus(deps?: RescueDeps): Promise<RescueStatusReport>;
+export type RescueDismissOutcome = 
+/** Nothing was stranded — no dialog was open. */
+"no-dialog"
+/** Cancel was pressed and the dialog is confirmed gone. */
+ | "dismissed"
+/** Cancel was pressed and the dialog is demonstrably still there (oddities §26). */
+ | "still-open"
+/** Cancel was pressed and the screen could not be re-read to confirm either way. */
+ | "unverified"
+/** Nothing was pressed. */
+ | "refused";
+export interface RescueDismissResult {
+    outcome: RescueDismissOutcome;
+    /** Which press worked, when one did. */
+    how: "cancel-button" | "cancel-click" | null;
+    before: UiState | null;
+    after: UiState | null;
+    /** Dialogs still stacked after this one; null when it could not be re-read. */
+    levelsRemaining: number | null;
+    detail: string;
+    remediation: string[];
+    notes: string[];
+    warnings: string[];
+}
+/** The two keys `rescue dismiss` needs, spelled the way each surface spells them. */
+export interface RescueDismissAck {
+    /** `--dangerously-dismiss-dialog`. */
+    dangerouslyDismissDialog?: boolean;
+}
+/**
+ * Close the dialog IN FRONT by pressing its own Cancel button — FGRD2's proven
+ * Cancel, generalized off the drive's abort path and onto a dialog no drive
+ * opened.
+ *
+ * EXACTLY ONE LIFO LEVEL PER INVOCATION. Sheets nest as `AXSheet` children of
+ * the sheet below and dismiss strictly last-in-first-out (MODALX1 §6). A loop
+ * that cleared a whole stack in one command would be a loop pressing an unknown
+ * number of buttons on an unknown number of dialogs; instead this closes the top
+ * one, re-reads, and reports how many remain so the caller decides.
+ *
+ * PROVEN, never assumed. The press reporting success is NOT closure: the
+ * detached editor of oddities §26 accepts an AXPress on its Cancel and stays
+ * exactly where it is. Closure is decided by a fresh census showing the stack one
+ * level shorter, and an unconfirmable press is reported as unconfirmed.
+ *
+ * WHAT IT CAN COST YOU: the dialog's own pending edits, and nothing else. The
+ * database is untouched, and a URL command parked behind a consent sheet is
+ * discarded with it (URLEN1).
+ */
+export declare function rescueDismiss(ack?: RescueDismissAck, deps?: RescueDeps): Promise<RescueDismissResult>;
+export type RescueRelaunchOutcome = "relaunched" | "refused" | "failed";
+export interface RescueRelaunchResult {
+    outcome: RescueRelaunchOutcome;
+    /** Which rung actually ended the process. */
+    endedBy: "quit" | "sigterm" | "sigkill" | "not-running" | null;
+    before: UiState | null;
+    after: UiState | null;
+    /** The step-by-step account of the ladder, always present. */
+    ladder: string[];
+    detail: string;
+    remediation: string[];
+    notes: string[];
+    warnings: string[];
+}
+/** The keys `rescue relaunch` needs. The second one is profile-dependent. */
+export interface RescueRelaunchAck {
+    /** `--yes`. */
+    yes?: boolean;
+    /** `--dangerously-force-quit`; required only under the `workstation` profile. */
+    dangerouslyForceQuit?: boolean;
+}
+/**
+ * End Things and start it again — the nuclear rung, and the ONLY cure this
+ * project has measured for the detached editor of oddities §26. DRVLAT1 §5 tried
+ * every other route against the same live dialog (its own Cancel backgrounded,
+ * foregrounded and after `AXRaise`; Escape; ⌘W then re-activate; a real HID click
+ * at the AX-resolved Cancel frame) and every one was inert.
+ *
+ * THE LADDER, each rung bounded:
+ *
+ *   1. ask Things to quit through its own scripting interface. Bounded, because
+ *      a standing sheet swallows ⌘Q and the `quit` verb can block behind one.
+ *   2. SIGTERM, and wait for the process to go.
+ *   3. SIGKILL — the lab's canonical reset for a modal that will not clear.
+ *   4. start it again in the BACKGROUND: we do not steal the screen to fix the
+ *      screen.
+ *   5. prove it: the process is answering, the database still reads as the shape
+ *      this version expects, and no dialog is open.
+ *
+ * WHAT IS LOST: the Things database is write-ahead-logged, so everything already
+ * committed survives a kill unconditionally. The ceiling is what was never
+ * committed — the edits sitting in the dialog being destroyed.
+ *
+ * WHAT COMES BACK: sync. While a dialog stands, Things stops sending changes to
+ * Things Cloud (oddities §24); killing the dialog with the process releases that,
+ * and everything written on this Mac in the meantime goes out.
+ *
+ * DELIBERATELY NOT GATED ON THE GUI CAPABILITY. Every other verb that touches the
+ * app needs the GUI grant, because it synthesizes input into someone's window.
+ * This one signals a process the user already owns, which needs no grant at all —
+ * and the machines that need it most are exactly the ones where the Accessibility
+ * path is what broke. The quit rung and the census still run through the granted
+ * seam when it is available, and are skipped without complaint when it is not.
+ */
+export declare function rescueRelaunch(ack?: RescueRelaunchAck, deps?: RescueDeps): Promise<RescueRelaunchResult>;
+/**
+ * The human render of `things rescue status`.
+ *
+ * A ROW WHOSE PROBE DID NOT ANSWER SAYS SO (issue #629). Printing a field's
+ * unset default ("none", "unknown") beside rows that WERE measured is exactly
+ * what made a stalled inspection read as a clean screen in the field, so an
+ * unproven probe renders as "not established" rather than as its default, and
+ * the probes are named again in full on the `unproven:` row.
+ */
+export declare function rescueStatusLines(report: RescueStatusReport): string[];
+/** The human render of `things rescue dismiss`. */
+export declare function rescueDismissLines(result: RescueDismissResult): string[];
+/** The human render of `things rescue relaunch`. */
+export declare function rescueRelaunchLines(result: RescueRelaunchResult): string[];