things-api 0.17.0 → 0.19.0

package/dist/deputy/install.d.ts

@@ -0,0 +1,319 @@
+import { type HelpersMode } from "../config.ts";
+import { type Wizard } from "../wizard.ts";
+import { type DeputyHello } from "./protocol.ts";
+/**
+ * Where the LaunchAgent plists live. THINGS_API_LAUNCH_AGENTS_DIR overrides
+ * for tests — WITHOUT it, every suite that exercises install/uninstall/reset
+ * mutates the DEVELOPER MACHINE's real ~/Library/LaunchAgents. That is not
+ * hypothetical: it deleted the live helpers' plists mid-`npm run check`
+ * twice on 2026-08-24 before this seam existed. Test setup must always set
+ * it alongside THINGS_API_STATE_DIR.
+ */
+export declare function launchAgentsDir(env?: NodeJS.ProcessEnv): string;
+export declare function deputyPlistPath(env?: NodeJS.ProcessEnv): string;
+export declare function readerPlistPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Where an install looks for the bundle when the caller names no path, in
+ * preference order: `deputy/prebuilt` — the signed + notarized bundle the
+ * release workflow stages into the published tarball, so an npm install needs
+ * neither Xcode nor a certificate — then `deputy/build`, the output of
+ * scripts/build-helpers.sh in a source checkout.
+ */
+export declare function helpersBundleCandidates(): string[];
+/**
+ * The first candidate bundle that carries a deputy executable; null when none
+ * does. Both candidates are READ only — nothing in the `things helpers` path
+ * ever writes inside the package directory, so the CLI works from a read-only
+ * package root (an npx cache); BUILDING a bundle there is the one operation
+ * that needs a writable checkout, and `--bundle <path>` covers a prebuilt one.
+ */
+export declare function helpersDefaultBuildPath(): string | null;
+/**
+ * The INSTALLED bundle's version, read prompt-free from its Info.plist
+ * (CFBundleShortVersionString, stamped from deputy/VERSION at build time).
+ * Null when nothing is installed or the plist is unreadable/unstamped. This is
+ * the version a passive upgrade notice compares against
+ * {@link EXPECTED_HELPERS_VERSION} without needing a running helper.
+ */
+export declare function installedHelpersVersion(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The reader's LaunchAgent. Two keys carry the whole host-universal rendezvous:
+ *
+ * - **`Sockets`** — launchd creates, binds, listens on and chmods the socket at
+ *   `socketPath`, which is OUR state directory, and hands the sandboxed reader
+ *   the already-listening fd at activation (`launch_activate_socket`). The
+ *   reader cannot bind outside its container, so launchd binding on its behalf
+ *   is the only way the rendezvous escapes it — and with the socket outside
+ *   every container, a client reaching it crosses no consent class.
+ * - **`EnvironmentVariables`** — the access token, minted by the installer and
+ *   written to a sibling file for clients. Delivering it through the plist is
+ *   what lets the reader keep its expected token out of the container too.
+ *
+ * The plist therefore CARRIES A SECRET and is written 0600 — the same
+ * same-user trust class as the token file itself.
+ */
+export declare function renderReaderPlist(appPath: string, socketPath: string, token: string): string;
+/**
+ * Mint the reader's access token and lay down the client half of the
+ * rendezvous: `<state>/reader`, 0700, holding a 0600 token file. Returns the
+ * token so the same value can be injected into the LaunchAgent.
+ *
+ * The installer mints it — not the reader — because the reader can only write
+ * inside its container, which is the placement this whole arrangement exists
+ * to leave. A fresh token per install is deliberate: install owns the pair
+ * wholesale, and rotating the secret costs nothing when both ends are rewritten
+ * in the same breath.
+ */
+export declare function mintReaderRendezvous(env: NodeJS.ProcessEnv): string;
+export interface DeputySigning {
+    state: "signed" | "adhoc" | "unsigned" | "unknown";
+    authority: string | null;
+}
+/** codesign facts about a binary (diagnostic output — may name mechanisms). */
+export declare function deputySigningInfo(binaryPath: string): DeputySigning;
+export interface HelpersInstallResult {
+    bundlePath: string;
+    plistPath: string;
+    stateDir: string;
+    signing: DeputySigning;
+    readerInstalled: boolean;
+    /** Reader grant state after install: null when the reader is absent or never answered. */
+    readerGranted: boolean | null;
+    warnings: string[];
+}
+/**
+ * Install (or reinstall) the helpers: copy the built bundle to its stable
+ * path, write both LaunchAgent plists, and (re)bootstrap them under launchd.
+ */
+export declare function installHelpers(options?: {
+    bundlePath?: string;
+}, env?: NodeJS.ProcessEnv): HelpersInstallResult;
+export interface HelpersRevocation {
+    /** One row per macOS permission-store reset attempted. */
+    tccResets: {
+        target: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    /**
+     * What made the identifiers resolvable for `tccutil`: the bundle this
+     * machine had installed, the packaged bundle registered on the spot, or
+     * nothing at all (the grants cannot be addressed from here).
+     */
+    resolvedVia: "installed" | "packaged" | "none";
+    /** The packaged bundle handed to LaunchServices, when that path was taken. */
+    registeredBundle: string | null;
+    /** The one leg no tool can perform — surfaced, never silently skipped. */
+    shortcutsNote: string;
+}
+export interface HelpersUninstallResult {
+    /** Files/directories that existed and were removed. */
+    removed: string[];
+    /** Null unless revocation was asked for. */
+    revocation: HelpersRevocation | null;
+    warnings: string[];
+}
+export interface HelpersUninstallOptions {
+    /**
+     * Also revoke both identities' macOS permission grants and delete their
+     * local state (the reader's bookmark container, the deputy's tokens/logs).
+     */
+    revoke?: boolean;
+}
+export interface HelpersUninstallDeps {
+    /** External tool runner (test seam — a real `tccutil` revokes live grants). */
+    runTool?: (bin: string, args: string[]) => {
+        ok: boolean;
+        output: string;
+    };
+    /** Where a packaged bundle lives for the LaunchServices fallback. */
+    packagedBundlePath?: () => string | null;
+}
+/**
+ * Stop both halves and remove their LaunchAgents + the installed bundle.
+ *
+ * By default the macOS grants and the local state (tokens, logs, the reader's
+ * bookmark) are KEPT: the TCC rows are keyed to the two signing identities and
+ * simply go dormant, so a later reinstall picks them straight back up with no
+ * second ceremony. `revoke` turns this into the ceremony's full inverse —
+ * grants revoked first (see {@link revokeGrants}), then the uninstall, then the
+ * reader's container and the deputy's state dir deleted (the read grant is a
+ * bookmark FILE, not a TCC row, so revoking it means deleting it).
+ *
+ * Every leg is independent and IDEMPOTENT: an already-uninstalled helper, an
+ * empty permission store, and absent directories are all fine — each leg does
+ * whatever is still outstanding, so this works from any partial state and a
+ * second run is an all-no-op.
+ */
+export declare function uninstallHelpers(options?: HelpersUninstallOptions, env?: NodeJS.ProcessEnv, deps?: HelpersUninstallDeps): HelpersUninstallResult;
+/** Restart the launchd-managed helpers (picks up a rebuilt installed bundle). */
+export declare function restartHelpers(): void;
+/**
+ * The one-time grant ceremony: open the reader in `--grant` mode (the panel
+ * must be presented by the SANDBOXED process — that is what makes the grant
+ * durable) and wait for the bookmark to land, confirmed via the reader's
+ * handshake. The panel opens INSIDE the Things data folder when it exists, so
+ * accepting is the only click. Interactive by design; returns when granted or
+ * on timeout, and verifies the database actually resolves inside the granted
+ * scope so a wrong-folder grant reports loudly instead of half-working.
+ */
+export declare function grantReader(env?: NodeJS.ProcessEnv): {
+    granted: boolean;
+    detail: string;
+};
+export type OnboardLeg = "reader-read-grant" | "automation-things" | "automation-system-events" | "accessibility" | "shortcuts";
+/**
+ * Which TIER a leg belongs to (docs/design/permissions-doctrine.md, Article V).
+ * The BASE tier gathers read + write capability, which is what every consumer
+ * of this package needs. The GUI tier adds the two grants that let the helpers
+ * drive the Things WINDOW — Accessibility and Automation → System Events — and
+ * is only gathered when it was asked for, because those two are the widest
+ * grants the pair ever holds and most households never need them.
+ */
+export type OnboardTier = "base" | "gui";
+/**
+ * Where a leg stands after the ceremony. `pending` is a HUMAN-pace outcome (a
+ * dialog left unanswered, a toggle not yet flipped) and is not a failure —
+ * rerunning resumes exactly where it stopped. Only `denied` means macOS (or
+ * the user) refused, and only that makes the command exit nonzero.
+ */
+export type OnboardState = "granted" | "denied" | "pending" | "skipped-not-installed";
+export interface OnboardStep {
+    leg: OnboardLeg;
+    /** The row label in the closing report. */
+    label: string;
+    /** The tier this leg belongs to — `gui` legs run only when that tier is in. */
+    tier: OnboardTier;
+    state: OnboardState;
+    /** True when the leg was already satisfied, detected without raising anything. */
+    alreadyGranted: boolean;
+    detail: string;
+}
+export interface HelpersOnboardResult {
+    /** The tier this run gathered: `base`, or `gui` (base plus the GUI legs). */
+    tier: OnboardTier;
+    /**
+     * How the GUI tier came to be included: the `--gui` flag, the `ui-enabled`
+     * config key already being on, the wizard's interactive question, or not at
+     * all. Reported so the ceremony's own output can say why it did what it did.
+     */
+    guiRequestedBy: "flag" | "config" | "wizard" | null;
+    /** True when this run turned `ui-enabled` on as part of a successful GUI tier. */
+    uiEnabledSet: boolean;
+    steps: OnboardStep[];
+    /**
+     * The legs that were going to put something on screen, surveyed prompt-free
+     * BEFORE the first one ran. Empty means the ceremony raised nothing.
+     */
+    outstanding: OnboardLeg[];
+    /** Any leg refused. */
+    denied: boolean;
+    /** Any leg still waiting on a human. */
+    pending: boolean;
+    /** The single closing line printed under the report. */
+    closing: string;
+}
+/** The deputy transport the ceremony drives (a test seam — see {@link OnboardDeps}). */
+export interface OnboardChannel {
+    hello(): DeputyHello;
+    request(fields: Record<string, unknown>, timeoutMs: number): Record<string, unknown>;
+    close(): void;
+}
+export interface OnboardDeps {
+    /** One line per step, as it happens. Default: stdout. */
+    progress?: (line: string) => void;
+    channel?: OnboardChannel;
+    /** Reader state, prompt-free: granted bookmark AND a database inside it. */
+    readerProbe?: () => {
+        granted: boolean;
+        locates: boolean;
+    } | null;
+    /** The reader's panel ceremony (default: {@link grantReader}). */
+    grant?: () => {
+        granted: boolean;
+        detail: string;
+    };
+    /** Best-effort deep link into System Settings. Default: `open <url>`. */
+    openUrl?: (url: string) => void;
+    sleep?: (ms: number) => void;
+    now?: () => number;
+    automationTimeoutMs?: number;
+    axTimeoutMs?: number;
+    axIntervalMs?: number;
+    /** How long to wait for the deputy's socket to appear (a just-installed helper is still coming up). */
+    deputyWaitMs?: number;
+    /**
+     * The Article V wizard. Default: built from TTY-ness (../wizard.ts). At a TTY
+     * it explains each dialog before the leg raises it and asks the tier question;
+     * off a TTY every method is inert and the ceremony behaves exactly as it did
+     * before the wizard existed.
+     */
+    wizard?: Wizard;
+    /** Is `ui-enabled` already on? Default: the stored config. */
+    uiEnabled?: () => boolean;
+    /** Turn `ui-enabled` on after a successful GUI tier. Default: the config file. */
+    setUiEnabled?: (value: boolean) => void;
+}
+/** What `onboardHelpers` is being asked to gather. */
+export interface OnboardOptions {
+    /** The configured routing mode, for the closing line. */
+    mode: HelpersMode;
+    /**
+     * Gather the GUI tier as well (`things helpers setup --gui`). When omitted,
+     * the tier is still included if `ui-enabled` is already on (a machine that
+     * has opted into GUI-driving is asking for the grants by definition), or if
+     * the wizard's interactive question is answered yes.
+     */
+    gui?: boolean;
+}
+/**
+ * The full onboarding ceremony behind `things helpers setup`: fire every
+ * consent macOS will ever ask for while a human is sitting there, then report
+ * where each one landed. Every leg is IDEMPOTENT — an already-granted leg is
+ * detected prompt-free (the deputy's own `hello` carries its TCC standing) and
+ * skipped — so a rerun on a fully onboarded machine raises nothing and reports
+ * all-green. Interactive by design: run it at the machine.
+ *
+ * Throws when the helpers are not installed or the deputy does not answer;
+ * every other outcome is reported per leg. See docs/design/helpers-onboarding.md.
+ *
+ * Runs under `withDefaultInterrupts` for its whole synchronous span, so Ctrl-C
+ * stops it at a gate AND inside the Accessibility wait (../wizard.ts, "Why a
+ * ceremony runs with the DEFAULT signal disposition"). Throws `CeremonyStopped`
+ * when the human stops at a gate.
+ */
+export declare function onboardHelpers(options: OnboardOptions, env?: NodeJS.ProcessEnv, deps?: OnboardDeps): HelpersOnboardResult;
+export interface DeputyHalfStatus {
+    plistInstalled: boolean;
+    loaded: boolean;
+    running: boolean;
+    socketPath: string;
+    /**
+     * The socket file exists but no handshake came back (a dead process that
+     * left its socket behind, or one wedged mid-request). Distinct from plain
+     * "not running": the remedy is `things helpers restart`, not an install.
+     */
+    hungSocket: boolean;
+    hello: DeputyHello | null;
+    signing: DeputySigning | null;
+    detail: string;
+}
+export interface ReaderHalfStatus extends DeputyHalfStatus {
+    installed: boolean;
+    granted: boolean;
+}
+export interface HelpersStatus {
+    /** The configured routing mode (`helpers-enabled`), not what it resolved to. */
+    mode: HelpersMode;
+    bundleInstalled: boolean;
+    /** The installed bundle's version (Info.plist), null when nothing is installed. */
+    installedVersion: string | null;
+    deputy: DeputyHalfStatus;
+    reader: ReaderHalfStatus;
+}
+/**
+ * Prompt-free status for both halves: launchd load state, a live handshake
+ * when each socket answers, and the installed bundle's signing facts. Works
+ * with routing disabled — inspect first, enable after.
+ */
+export declare function helpersStatus(mode: HelpersMode, env?: NodeJS.ProcessEnv): HelpersStatus;