things-api 0.9.0 → 0.11.0

package/dist/write/operations.d.ts

@@ -4,8 +4,19 @@
  * per-vector matrices (data, produced by the lab), not here.
  */
 import type { IsoDate, ReminderTime } from "../model/dates.ts";
-export declare const OPERATION_KINDS: readonly ["todo.add", "todo.update", "todo.complete", "todo.cancel", "todo.reopen", "todo.move", "todo.set-tags", "todo.replace-checklist", "todo.edit-checklist-item", "todo.delete", "project.add", "project.update", "project.complete", "project.delete", "area.add", "area.delete", "tag.add", "tag.delete", "trash.empty", "reorder", "todo.duplicate", "area.update", "tag.update", "project.move", "todo.restore", "project.duplicate", "project.cancel", "project.reopen", "project.restore", "project.set-tags", "todo.backdate", "todo.add-logged", "heading.rename", "heading.archive", "heading.unarchive", "heading.create", "todo.clear-dated-reminder"];
+export declare const OPERATION_KINDS: readonly ["todo.add", "todo.update", "todo.complete", "todo.cancel", "todo.reopen", "todo.move", "todo.set-tags", "todo.replace-checklist", "todo.edit-checklist-item", "todo.delete", "project.add", "project.update", "project.complete", "project.delete", "area.add", "area.delete", "tag.add", "tag.delete", "trash.empty", "reorder", "todo.duplicate", "area.update", "tag.update", "project.move", "todo.restore", "project.duplicate", "project.cancel", "project.reopen", "project.restore", "project.set-tags", "todo.backdate", "todo.add-logged", "heading.rename", "heading.archive", "heading.unarchive", "heading.create", "todo.clear-dated-reminder", "todo.make-repeating", "todo.reschedule-repeat", "todo.pause-repeat", "todo.resume-repeat", "todo.convert-to-project", "heading.convert-to-project", "project.reschedule-repeat", "project.pause-repeat", "project.resume-repeat", "area.reorder", "project.make-repeating", "project.create-repeating"];
 export type OperationKind = (typeof OPERATION_KINDS)[number];
+/**
+ * Operations delivered EXCLUSIVELY through the Accessibility GUI ("ui")
+ * vector — GUI-only transforms with no headless spelling. Each drives the
+ * local Things app, so all are two-key gated: the `ui.enabled` config plus a
+ * per-call `dangerouslyDriveGui` acknowledgement (H-UI-DRIVE). Kept as data so
+ * the guard and the pipeline agree on the set.
+ */
+export declare const UI_DRIVE_OPS: readonly OperationKind[];
+export declare function isUiDriveOp(op: OperationKind): boolean;
+/** Recurrence frequency the minimal v1 GUI rule vocabulary supports. */
+export type RepeatFrequency = "daily" | "weekly" | "monthly" | "yearly";
 /** `when` scheduling value: list keyword or a concrete date. */
 export type WhenValue = "today" | "evening" | "anytime" | "someday" | IsoDate;
 /** Container reference by uuid or (unique, case-insensitive) title. */
@@ -271,6 +282,120 @@ export interface ReorderParams {
     strategy?: ReorderStrategy;
 }
 export type EmptyParams = Record<string, never>;
+/**
+ * Move an area to a new position in the canonical area order. Area order has
+ * no headless spelling at all (P6/O13) — this is delivered by the ui vector's
+ * drag driver. Exactly ONE of before / after / position is required.
+ */
+export interface AreaReorderParams {
+    /** The area to move: uuid or unique case-insensitive title. */
+    target: string;
+    /** Place it immediately ABOVE this area (uuid or unique title). */
+    before?: string;
+    /** Place it immediately BELOW this area (uuid or unique title). */
+    after?: string;
+    /** Move it to the first or last area slot. Exclusive with before/after. */
+    position?: "first" | "last";
+}
+/** Weekday name (weekly day-of-week set; monthly/yearly nth-weekday anchor). */
+export type Weekday = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+export declare const WEEKDAYS: readonly Weekday[];
+/** The ordinal a monthly/yearly nth-weekday anchor selects (1st..5th, or last). */
+export type WeekdayOrdinal = 1 | 2 | 3 | 4 | 5 | "last";
+/**
+ * A monthly (or yearly) day anchor — the mutually-exclusive forms the Repeat
+ * dialog's month row offers (UIC1 field map). Exactly one shape:
+ *  - `{ day }`     — a day-of-month (1..31, or "last" = the month's last day);
+ *  - `{ weekday, ordinal }` — the nth (or last) weekday of the month.
+ */
+export type MonthlyAnchor = {
+    day: number | "last";
+} | {
+    weekday: Weekday;
+    ordinal: WeekdayOrdinal;
+};
+/** A yearly anchor: a month (1..12) plus the monthly-style day anchor. */
+export type YearlyAnchor = {
+    month: number;
+} & MonthlyAnchor;
+/**
+ * The Repeat dialog's "Ends" bound (single-choice pop-up, UIC1). Omit for the
+ * dialog default (`never`). `on-date` is the date picker; `after` the count
+ * field (the ORIGINAL number of occurrences, not the remaining tally).
+ */
+export type RepeatEnds = {
+    kind: "never";
+} | {
+    kind: "on-date";
+    date: IsoDate;
+} | {
+    kind: "after";
+    count: number;
+};
+/**
+ * Set (make-repeating) or edit (reschedule-repeat) a to-do's or project's
+ * recurrence rule through the GUI's Repeat dialog. The BASE vocabulary is
+ * `frequency` + `interval`; every other field is OPTIONAL and defaults to the
+ * dialog's own default, so a `{ uuid, frequency, interval }` call is unchanged.
+ *
+ * The optional fields cover the full UIC1 dialog field map. Combinations are
+ * validated (assertRepeatRule): a per-frequency field on the wrong frequency is
+ * refused, and the modal month anchor is a discriminated shape (day-of-month OR
+ * nth-weekday, never a contradictory bag).
+ */
+export interface RepeatRuleParams {
+    uuid: string;
+    /** The recurrence unit (also the "after completion" cadence when afterCompletion). */
+    frequency: RepeatFrequency;
+    /** "every N units", 1–99. */
+    interval: number;
+    /**
+     * After-COMPLETION cadence instead of a fixed schedule (rule type tp=1): the
+     * next occurrence is N units after the prior instance RESOLVES. Mutually
+     * exclusive with the calendar anchors (weekdays/monthly/yearly) — an
+     * after-completion rule has no calendar day.
+     */
+    afterCompletion?: boolean;
+    /**
+     * WEEKLY only: the set of weekdays the rule fires on (dialog day-of-week
+     * toggles + "+"). Omit for the single anchor weekday the dialog defaults to.
+     */
+    weekdays?: Weekday[];
+    /** MONTHLY only: the day-of-month or nth-weekday anchor (dialog month row). */
+    monthly?: MonthlyAnchor;
+    /** YEARLY only: the month + day anchor (dialog year row). */
+    yearly?: YearlyAnchor;
+    /** The "Ends" bound (dialog default: never). */
+    ends?: RepeatEnds;
+    /** "Add reminders" time-of-day (`HH:mm`, 24h) on the spawned instances. */
+    reminder?: ReminderTime;
+    /** "Add deadlines": the template deadlines its instances. */
+    deadline?: boolean;
+    /**
+     * With deadline: start the instance N days BEFORE its deadline (the dialog's
+     * "start N days earlier" field, revealed by "Add deadlines"). Integer ≥ 0;
+     * implies `deadline` (a start offset only exists on a deadlined template).
+     */
+    startDaysEarlier?: number;
+}
+/**
+ * Create a project and, in the same call, promote it to a repeating series
+ * (the two-step composite of UIC4-f). The create seeds a pure-AX taxonomy —
+ * an `area` lands the project as a selectable AREA-view row; otherwise it is
+ * created in Someday — so the promote never needs a coercion. The two legs are
+ * NOT atomic: the created project persists even if the promote refuses.
+ */
+export interface ProjectCreateRepeatingParams {
+    title: string;
+    notes?: string;
+    /** Destination area (uuid or unique name); when omitted the project is created in Someday. */
+    area?: ContainerRef;
+    deadline?: IsoDate;
+    todos?: string[];
+    frequency: RepeatFrequency;
+    /** "every N units", 1–99. */
+    interval: number;
+}
 export interface OperationParamsMap {
     "todo.add": TodoAddParams;
     "todo.update": TodoUpdateParams;
@@ -309,6 +434,18 @@ export interface OperationParamsMap {
     "heading.unarchive": HeadingUnarchiveParams;
     "heading.create": HeadingCreateParams;
     "todo.clear-dated-reminder": UuidParams;
+    "todo.make-repeating": RepeatRuleParams;
+    "todo.reschedule-repeat": RepeatRuleParams;
+    "todo.pause-repeat": UuidParams;
+    "todo.resume-repeat": UuidParams;
+    "todo.convert-to-project": UuidParams;
+    "heading.convert-to-project": UuidParams;
+    "project.reschedule-repeat": RepeatRuleParams;
+    "project.pause-repeat": UuidParams;
+    "project.resume-repeat": UuidParams;
+    "area.reorder": AreaReorderParams;
+    "project.make-repeating": RepeatRuleParams;
+    "project.create-repeating": ProjectCreateRepeatingParams;
 }
 /** Explicit confirmations for operations with cascading or permanent effects (never defaulted). */
 export interface Acknowledgements {
@@ -320,4 +457,11 @@ export interface Acknowledgements {
     dangerouslyPermanent?: boolean;
     /** Confirm that deleting a parent tag permanently deletes ALL of its descendant tags. */
     acknowledgeTagSubtree?: boolean;
+    /**
+     * Confirm a GUI-driven ("ui" vector) operation: it drives the LOCAL Things
+     * app through the Accessibility API, may foreground Things and briefly take
+     * over UI focus on this machine, and requires an unlocked session. The
+     * second of the two keys (the first is the `ui.enabled` config).
+     */
+    dangerouslyDriveGui?: boolean;
 }

package/dist/write/operations.js

@@ -36,5 +36,53 @@ export const OPERATION_KINDS = [
     "heading.unarchive",
     "heading.create",
     "todo.clear-dated-reminder",
+    "todo.make-repeating",
+    "todo.reschedule-repeat",
+    "todo.pause-repeat",
+    "todo.resume-repeat",
+    "todo.convert-to-project",
+    "heading.convert-to-project",
+    "project.reschedule-repeat",
+    "project.pause-repeat",
+    "project.resume-repeat",
+    "area.reorder",
+    "project.make-repeating",
+    "project.create-repeating",
+];
+/**
+ * Operations delivered EXCLUSIVELY through the Accessibility GUI ("ui")
+ * vector — GUI-only transforms with no headless spelling. Each drives the
+ * local Things app, so all are two-key gated: the `ui.enabled` config plus a
+ * per-call `dangerouslyDriveGui` acknowledgement (H-UI-DRIVE). Kept as data so
+ * the guard and the pipeline agree on the set.
+ */
+export const UI_DRIVE_OPS = [
+    "todo.make-repeating",
+    "todo.reschedule-repeat",
+    "todo.pause-repeat",
+    "todo.resume-repeat",
+    "todo.convert-to-project",
+    "heading.convert-to-project",
+    "project.reschedule-repeat",
+    "project.pause-repeat",
+    "project.resume-repeat",
+    "area.reorder",
+    // Pure-AX (UIC4): the project is selected as a content-table ROW via a
+    // settable AXSelectedRows, then Items ▸ Repeat… drives the same dialog. The
+    // area-less-anytime taxonomy needs a Someday coercion first, orchestrated by
+    // runMakeRepeatingProject — but the drive itself is a ui-vector op.
+    "project.make-repeating",
+];
+export function isUiDriveOp(op) {
+    return UI_DRIVE_OPS.includes(op);
+}
+export const WEEKDAYS = [
+    "sunday",
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
 ];
 //# sourceMappingURL=operations.js.map

package/dist/write/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/write/operations.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,wBAAwB;IACxB,0BAA0B;IAC1B,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,aAAa;IACb,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,2BAA2B;CACnB,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/write/operations.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,wBAAwB;IACxB,0BAA0B;IAC1B,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,aAAa;IACb,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,2BAA2B;IAC3B,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,yBAAyB;IACzB,4BAA4B;IAC5B,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,wBAAwB;IACxB,0BAA0B;CAClB,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,qBAAqB;IACrB,wBAAwB;IACxB,mBAAmB;IACnB,oBAAoB;IACpB,yBAAyB;IACzB,4BAA4B;IAC5B,2BAA2B;IAC3B,sBAAsB;IACtB,uBAAuB;IACvB,cAAc;IACd,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,oEAAoE;IACpE,wBAAwB;CAChB,CAAC;AAEX,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AA+UD,MAAM,CAAC,MAAM,QAAQ,GAAuB;IAC1C,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC"}

package/dist/write/pipeline.d.ts

@@ -8,7 +8,7 @@ import { type LikelyCause } from "./failure-hints.ts";
 import { type HazardId } from "./guards.ts";
 import type { Acknowledgements, OperationKind, OperationParamsMap } from "./operations.ts";
 import type { VectorId, WriteVector } from "./vectors/types.ts";
-import { type DeltaSpec } from "./verify/delta.ts";
+import { type DeltaSpec, type RepeatingDiscovery } from "./verify/delta.ts";
 import { type PollerDeps } from "./verify/poller.ts";
 export interface WriteOptions extends Acknowledgements {
     /** Caps vector selection; defaults from the config profile. */
@@ -18,6 +18,13 @@ export interface WriteOptions extends Acknowledgements {
     verifyTimeoutMs?: number;
     /** Return the plan without executing (nothing is audited). */
     dryRun?: boolean;
+    /**
+     * Create any tag named in this op's tags that does not exist yet (through the
+     * clean `make new tag` path, mkdir-p for `parent/child`) BEFORE applying —
+     * turning what would be an H-UNKNOWN-TAG refusal into a create-then-apply.
+     * Handled by the client's tag-prep orchestrator, above `runMutation`.
+     */
+    createTags?: boolean;
     /** Audit attribution. */
     actor?: string;
     /** Compound-operation grouping (set by orchestrators, not callers). */
@@ -25,6 +32,26 @@ export interface WriteOptions extends Acknowledgements {
         id: string;
         role: "leg" | "summary";
     };
+    /**
+     * Undo back-reference (set by the undo executor, not callers): the token of
+     * the original mutation this write inverts. Recorded on the audit trail so an
+     * already-undone mutation is distinguishable from a nonexistent one.
+     */
+    undoOf?: string;
+    /**
+     * Consumer IANA zone for THIS write, overriding the client's default zone.
+     * Only affects the clock-relative `when` tokens (today/evening) when
+     * {@link normalizeWhen} is set. Reminder times stay wall-clock and untranslated.
+     */
+    zone?: string;
+    /**
+     * Normalize a CONSUMER-provided clock-relative `when` (today/evening) to the
+     * effective consumer zone BEFORE dispatch — set by the consumer entry points
+     * (the client's `run`, batch), NEVER by the internal orchestrators (undo,
+     * reorder), whose when tokens converse with app-written host state and must
+     * stay on the host clock.
+     */
+    normalizeWhen?: boolean;
 }
 export interface MutationPlan {
     op: OperationKind;
@@ -41,6 +68,21 @@ export type MutationResult = {
     observed: Record<string, unknown> | null;
     vector: VectorId;
     tier: DisruptionTier;
+    /**
+     * The undo token for this mutation (ADDITIVE): pass it to
+     * `things undo --txn <token>` (MCP `txn`) to invert exactly this change,
+     * unaffected by any other mutations made in between.
+     */
+    undoToken?: string;
+    /**
+     * Make-repeating conversions (todo/project make-repeating, and
+     * project.create-repeating via its promote leg): the discovered template
+     * uuid, the FK-derived current-occurrence instance (use this for the
+     * VISIBLE item), and the replaced original uuid — plus `childrenReplaced`
+     * for project conversions. `uuid` still equals `templateUuid` (use it to
+     * reschedule the repeat). Absent for every other op.
+     */
+    repeating?: RepeatingDiscovery;
     /** Advisory notes (e.g. a changed environment tuple — consent may re-prompt later). */
     warnings?: string[];
 } | {
@@ -56,7 +98,7 @@ export type MutationResult = {
 } | {
     kind: "blocked";
     op: OperationKind;
-    reason: "hazard" | "disruption-tier" | "drift" | "lock" | "environment";
+    reason: "hazard" | "disruption-tier" | "drift" | "lock" | "environment" | "clock";
     hazard?: HazardId;
     detail: string;
     remediation: string;
@@ -92,9 +134,38 @@ export interface WriteDeps {
     /** Seam: installed Things proxy shortcuts, for the pre-dispatch availability gate (availability.ts). */
     shortcutProxies?: () => ShortcutsState;
     now?: () => Date;
+    /** Default consumer IANA zone (client-resolved from THINGS_TZ); normalizes consumer `when` tokens. */
+    zone?: string;
     poller?: PollerDeps;
     pkgVersion?: string;
 }
 export declare function readAuthToken(db: DatabaseSync): string | null;
+/**
+ * Normalize a CONSUMER-provided clock-relative `when` for the effective zone,
+ * so the app (which would interpret the bare word on the HOST clock) never sees
+ * a relative token that means a different calendar date for the consumer.
+ *
+ * - `today` → the consumer-zone calendar date, dispatched as an explicit
+ *   `when=YYYY-MM-DD` (with any reminder still appended) so verification agrees
+ *   by construction. When the consumer's today already equals the app's today
+ *   the token is left as-is (byte-identical dispatch). A consumer-today that is
+ *   host-yesterday yields a past startDate — coherent (lands in Today with
+ *   overdue-start semantics), documented, not special-cased.
+ * - `evening` → This Evening exists ONLY for the app machine's own current day
+ *   (the startBucket=1 rows whose startDate is exactly the app's today; an
+ *   "evening of another day" is not representable in Things' model, not even in
+ *   the GUI — see src/read/views.ts). Refused fail-closed when the dates differ.
+ *
+ * Reminder times are wall-clock and tz-less in Things' own model — never
+ * translated here.
+ */
+export declare function normalizeConsumerWhen(params: Record<string, unknown>, now: Date, zone: string): {
+    ok: true;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    detail: string;
+    remediation: string;
+};
 export declare function runMutation<K extends OperationKind>(deps: WriteDeps, op: K, params: OperationParamsMap[K], options?: WriteOptions): Promise<MutationResult>;
 export declare function fingerprintLabel(fp: FingerprintStatus, config: ThingsApiConfig): "ok" | "drift" | "user-accepted" | "unknown";