@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.20

package/src/lib/timetrack.d.ts

@@ -0,0 +1,561 @@
+/** What every write answers: it waits in the app until the user approves or rejects it. */
+export type TimetrackQueued = {
+    status: 'queued';
+    approvalId: string;
+};
+/** Where a queued write stands. `result` is what the op answered once approved and carried out. */
+export type TimetrackApprovalStatus = {
+    status: 'queued' | 'rejected' | 'expired';
+    approvalId: string;
+} | {
+    status: 'approved';
+    approvalId: string;
+    result?: unknown;
+    error?: string;
+};
+export type TimetrackIssue = {
+    key: string;
+    id: string;
+    summary: string;
+    issueType: string;
+    parentKey?: string;
+    subject?: string;
+};
+export type TimetrackStatus = {
+    version: number;
+    jiraReady: boolean;
+    tempoReady: boolean;
+    projects: {
+        key: string;
+        name: string;
+    }[];
+    subjectField: string;
+};
+export type TimetrackInstance = {
+    levels: {
+        hierarchyLevel: number;
+        typeNames: string[];
+    }[];
+    suggestedParenting: 'parent-field' | 'issue-link';
+    subjectFieldCandidates: {
+        id: string;
+        name: string;
+    }[];
+};
+export type TimetrackRepoProject = {
+    repoPath: string;
+    projectKey?: string;
+    private: boolean;
+    inherited: boolean;
+    suggestedProjectKey?: string;
+};
+/** One standing statement about what work in a context is logged against. */
+export type TimetrackAttributionRule = {
+    id: string;
+    repoPath?: string;
+    branch?: string;
+    appId?: string;
+    /** The issue the rule names, or nothing when it donates its time or names a stand-in instead. */
+    issueKey?: string;
+    /** The stand-in the rule names, as an id into what `timetrackStandIns` answers. */
+    standInId?: string;
+    /** Whether the rule donates its time to the work around it rather than naming an issue. */
+    donates: boolean;
+    createdAtMs: number;
+};
+/** One standing statement about a path: whether it is work, and which project it files into. */
+export type TimetrackProjectLinkRule = {
+    id: string;
+    path: string;
+    projectKey?: string;
+    private: boolean;
+    createdAtMs: number;
+};
+/** The settings that decide what a day's work is named. It holds no host, no account and no token. */
+export type TimetrackRules = {
+    dayTargetMs: number;
+    gapFillMs: number;
+    dayStartHour: number;
+    attributionRules: TimetrackAttributionRule[];
+    projectLinks: TimetrackProjectLinkRule[];
+    backgroundProjects: string[];
+    noWorkContextApps: string[];
+    holdsWorkApps: string[];
+};
+/**
+ * One name the user gave work that Jira does not hold yet.
+ *
+ * Nothing in this CLI opens or resolves a stand-in, because the name is the user's own word for their
+ * work and the app is where they give it. A delete is allowed: it takes a name away rather than
+ * putting one on the day.
+ */
+export type TimetrackStandIn = {
+    id: string;
+    name: string;
+    projectKey?: string;
+    state: 'open' | 'resolved';
+    /** The issue it resolved to. Absent while it is open. */
+    issueKey?: string;
+    /** The local day keys that hold bands of it, oldest first. */
+    days: string[];
+    author: 'user' | 'agent';
+    createdAtMs: number;
+    /** The checkout the app opened it for. Absent on one the user opened by hand. */
+    openedFor?: string;
+    /**
+     * The branch of that checkout it covers. Absent on a record opened before the grain was the branch,
+     * which is why such a record covers the whole checkout and blocks every branch of it.
+     */
+    openedForBranch?: string;
+    /** The directory of that branch it covers, where the branch names no piece of work of its own. */
+    openedForWorkPath?: string;
+};
+/** One commit a split reads a directory out of: the day it counts toward, and its changed files. */
+export type TimetrackWorkCommit = {
+    day: string;
+    paths: string[];
+};
+/** One directory a split names, with the days of the record that worked in it. */
+export type TimetrackStandInPiece = {
+    workPath: string;
+    days: string[];
+    commits: number;
+};
+/** What a split would do, or did. `candidates` is every directory; `pieces` is what gets written. */
+export type TimetrackStandInSplit = {
+    candidates: TimetrackStandInPiece[];
+    pieces: TimetrackStandInPiece[];
+    /** The days no piece claims, which the record being split keeps rather than the split refusing. */
+    remainder: string[];
+    standIns: TimetrackStandIn[];
+};
+/**
+ * What the checkout-wide naming offer says about one day, offers and refusals alike.
+ *
+ * A card the day screen never draws is the hardest thing to ask about, because every step that can
+ * stop it is invisible from the screen. `declines` names the step that stopped.
+ */
+export type TimetrackNaming = {
+    day: string;
+    /** Whether a Tempo token is stored. Without one every checkout declines with `no-history`. */
+    tempoReady: boolean;
+    /** How far the read of the user's Tempo history got. */
+    history: 'loading' | 'no-token' | 'ready' | 'failed';
+    /** How many worklogs the span holds, whatever project they are in. */
+    historyWorklogs: number;
+    /** What the read failed with. Absent unless `history` is `failed`. */
+    historyMessage?: string;
+    offers: TimetrackNamingOffer[];
+    declines: TimetrackNamingDecline[];
+};
+export type TimetrackNamingOffer = {
+    repoPath: string;
+    projectKey: string;
+    issueKey: string;
+    summary: string;
+    days: number;
+    loggedMs: number;
+    /** How much of the project's logged time went to this one issue, from 0 to 1. */
+    share: number;
+};
+export type TimetrackNamingDecline = {
+    repoPath: string;
+    reason: 'already-named' | 'named-by-stand-in' | 'no-project-link' | 'no-history' | 'project-too-small' | 'too-few-days' | 'share-too-low';
+    projectKey?: string;
+    issueKey?: string;
+    days?: number;
+    loggedMs?: number;
+    projectMs?: number;
+    share?: number;
+};
+/** One day's evidence, straight out of the app's encrypted store. `events` is opaque here on purpose. */
+export type TimetrackDayEvents = {
+    day: string;
+    fromMs: number;
+    toMs: number;
+    events: unknown[];
+};
+/** One transcribed stretch of the user's own microphone during a call. */
+export type TimetrackTranscriptChunk = {
+    atMs: number;
+    callStartedAtMs: number;
+    appId: string;
+    model: string;
+    language: string | null;
+    text: string;
+};
+export type TimetrackTranscriptDay = {
+    day: string;
+    chunks: TimetrackTranscriptChunk[];
+};
+/** One row of a day as the app's own review drew it. Every edit names a row by this `id`. */
+export type TimetrackRow = {
+    id: string;
+    issueKey?: string;
+    standInId?: string;
+    description: string;
+    fromMs: number;
+    toMs: number;
+    durationMs: number;
+    observedMs: number;
+    laneKey?: string;
+    state: string;
+    confidence: string;
+    edited: boolean;
+    hidden: boolean;
+    /** What `timetrackAskAutoMode` takes to ask about the row again. Absent where the app offers no ask. */
+    autoModeSubject?: TimetrackAutoModeSubject;
+};
+/** A day as the screen draws it: the rows, the ones taken off the timeline, and its totals. */
+export type TimetrackDayRows = {
+    day: string;
+    rows: TimetrackRow[];
+    hidden: TimetrackRow[];
+    proposedMs: number;
+    loggedMs: number;
+    targetMs: number;
+    unattributedMs: number;
+    warnings: {
+        kind: string;
+        detail: string;
+    }[];
+    behind?: {
+        fromMs: number;
+        toMs: number;
+        issueKey: string;
+        laneKey: string;
+        durationMs: number;
+    }[];
+};
+/** One change to one row, named by the id `timetrackDayRows` answered. */
+export type TimetrackRowEdit = {
+    kind: 'range';
+    rowId: string;
+    fromMs: number;
+    toMs: number;
+} | {
+    kind: 'issue';
+    rowId: string;
+    issueKey: string;
+} | {
+    kind: 'description';
+    rowId: string;
+    description: string;
+} | {
+    kind: 'state';
+    rowId: string;
+    state: 'accepted' | 'rejected';
+} | {
+    kind: 'hidden';
+    rowId: string;
+    hidden: boolean;
+} | {
+    kind: 'reset';
+    rowId: string;
+};
+export type TimetrackEditedDay = TimetrackDayRows & {
+    applied: number;
+};
+export type TimetrackWorklog = {
+    day: string;
+    issueKey: string;
+    description: string;
+    fromMs: number;
+    toMs: number;
+    durationMs: number;
+};
+/** One of the user's own Tempo worklogs, whoever wrote it. */
+export type TimetrackTempoWorklog = {
+    id: string;
+    day: string;
+    /** The local start as `HH:MM`. An app older than this CLI leaves it out for a worklog at midnight. */
+    startTime?: string;
+    startMs: number;
+    durationMs: number;
+    /** Absent where Jira no longer resolves the issue Tempo names. */
+    issueKey?: string;
+    issueId: string;
+    description: string;
+};
+export type TimetrackTempoWorklogs = {
+    from: string;
+    to: string;
+    worklogs: TimetrackTempoWorklog[];
+};
+export type TimetrackTempoDelete = {
+    deleted: {
+        id: string;
+        day: string;
+        startTime: string;
+        minutes: number;
+        issueKey?: string;
+        description: string;
+    };
+    /** Set when Tempo dropped the worklog but the app's ledger kept the entry that owned it. */
+    unrecorded?: string;
+};
+export type TimetrackTempoSyncWrite = {
+    kind: 'create' | 'update' | 'delete';
+    proposalId: string;
+    issueKey?: string;
+    fromMs: number;
+    durationMs: number;
+    description: string;
+    reason: string;
+    /** The worklog an update or a delete targets. */
+    tempoWorklogId?: string;
+    /** Why the row would be held back rather than sent. */
+    blocked?: string;
+};
+export type TimetrackTempoSyncRowResult = {
+    kind: 'create' | 'update' | 'delete';
+    proposalId: string;
+    status: 'written' | 'blocked' | 'skipped' | 'failed';
+    issueKey?: string;
+    tempoWorklogId?: string;
+    detail?: string;
+};
+/** What a sync of one day would write, and what a confirmed write did. */
+export type TimetrackTempoSync = {
+    day: string;
+    /** Covers the write set only. A write must name it, and the app refuses one a fresh plan does not match. */
+    planHash: string;
+    writes: TimetrackTempoSyncWrite[];
+    unchanged: number;
+    skipped: number;
+    unresolvedKeys: string[];
+    foreign: {
+        id: string;
+        issueKey?: string;
+        issueId: string;
+        fromMs: number;
+        durationMs: number;
+        description: string;
+    }[];
+    coveredMs: number;
+    run?: {
+        rows: TimetrackTempoSyncRowResult[];
+        retryCount: number;
+        unrecorded?: string;
+    };
+};
+/** One entry of a calendar the app reads, all-day and declined ones included. */
+export type TimetrackCalendarEvent = {
+    calendarId: string;
+    day: string;
+    startMs: number;
+    endMs: number;
+    allDay: boolean;
+    title: string;
+    /** Everyone invited except rooms, the user included. */
+    attendeeCount: number;
+    /** The user's own answer, or `organizer` where the entry has no attendee list. */
+    response: 'accepted' | 'declined' | 'tentative' | 'needsAction' | 'organizer' | 'unknown';
+};
+export type TimetrackCalendarEvents = {
+    from: string;
+    to: string;
+    calendarIds: string[];
+    events: TimetrackCalendarEvent[];
+};
+/**
+ * Where the app writes the port and the token, which is its data directory on each platform.
+ *
+ * `TIMETRACK_AGENT_DISCOVERY` names the file directly, for a machine whose app data lives somewhere
+ * else and for a test.
+ */
+export declare const timetrackDiscoveryPath: () => string;
+/**
+ * The name the approval queue shows for this caller: `TIMETRACK_CLIENT` when set, Claude Code when it
+ * runs this, and nothing otherwise.
+ */
+export declare const timetrackClientName: () => string | undefined;
+/**
+ * Asks the running Timetrack app to carry out one operation.
+ *
+ * It is the only way this package reaches Jira. The token lives in the app's keychain entry and in no
+ * repository, so a checkout an agent works in holds nothing worth stealing and nothing to rotate.
+ */
+export declare const askTimetrack: <T>(request: Record<string, unknown> & {
+    op: string;
+}) => Promise<T>;
+export declare const timetrackStatus: () => Promise<TimetrackStatus>;
+export declare const timetrackNaming: (day: string) => Promise<TimetrackNaming>;
+export declare const timetrackInstance: () => Promise<TimetrackInstance>;
+export declare const timetrackIssue: (key: string) => Promise<TimetrackIssue>;
+export declare const timetrackSearch: (options: {
+    text?: string;
+    projectKey?: string;
+    assignedToMe?: boolean;
+    limit?: number;
+}) => Promise<TimetrackIssue[]>;
+export declare const timetrackRepoProject: (repoPath: string) => Promise<TimetrackRepoProject>;
+/** Queues a new issue, filed with the app's own ticket settings once the user approves it. */
+export declare const timetrackCreateIssue: (options: {
+    summary: string;
+    description?: string;
+    projectKey?: string;
+    issueTypeName?: string;
+    parentKey?: string;
+    subject?: string;
+}) => Promise<TimetrackQueued>;
+/** Queues a row for the day it belongs to. It is a row on the day once approved, not a Tempo entry. */
+export declare const timetrackAddWorklog: (options: {
+    issueKey: string;
+    description?: string;
+    fromMs: number;
+    durationMs: number;
+}) => Promise<TimetrackQueued>;
+export declare const timetrackDayEvents: (day: string) => Promise<TimetrackDayEvents>;
+export declare const timetrackTranscriptDay: (day: string) => Promise<TimetrackTranscriptDay>;
+export declare const timetrackDayRows: (day: string) => Promise<TimetrackDayRows>;
+/**
+ * Queues the stated edits to a day's rows. Once approved, the result is the day as it reads afterwards.
+ *
+ * `applied` in that result counts the edits that found their row: a day the collectors keep changing
+ * can drop a row a caller read a moment ago.
+ */
+export declare const timetrackEditDay: (options: {
+    day: string;
+    edits: readonly TimetrackRowEdit[];
+}) => Promise<TimetrackQueued>;
+/** Reads the user's own Tempo worklogs from Tempo, both days included. The app caps the span at 92 days. */
+export declare const timetrackTempoWorklogs: (options: {
+    from: string;
+    to: string;
+}) => Promise<TimetrackTempoWorklogs>;
+/**
+ * Plans a Tempo sync of one day exactly as the app's Sync page does. It writes nothing, so it is
+ * answered at once. The app moves its review to the day.
+ */
+export declare const timetrackTempoSync: (day: string) => Promise<TimetrackTempoSync>;
+/** Queues the write of the plan whose hash the user confirmed. The app checks the hash again on approval. */
+export declare const timetrackTempoSyncWrite: (options: {
+    day: string;
+    planHash: string;
+}) => Promise<TimetrackQueued>;
+/**
+ * Queues the delete of one of the user's own Tempo worklogs. Once approved, the app refuses an id that
+ * is not among the account's own worklogs on `day`, and drops the ledger entry that owned it.
+ */
+export declare const timetrackTempoDelete: (options: {
+    day: string;
+    worklogId: string;
+}) => Promise<TimetrackQueued>;
+/** Reads the calendars the app watches, both days included. The app caps the span at 92 days. */
+export declare const timetrackCalendarEvents: (options: {
+    from: string;
+    to: string;
+}) => Promise<TimetrackCalendarEvents>;
+export declare const timetrackRules: () => Promise<TimetrackRules>;
+/**
+ * Queues a read of the agent session logs under `paths` again, so sessions the app dropped while no
+ * project link held them are stored. Once approved, the read runs in the background.
+ *
+ * With `replace`, the re-read overwrites the samples, spend and prompts the store holds for those
+ * sessions, which is how a parser fix reaches days already stored.
+ */
+export declare const timetrackResyncAgentSessions: (paths: readonly string[], options?: {
+    replace?: boolean;
+}) => Promise<TimetrackQueued>;
+export declare const timetrackStandIns: () => Promise<TimetrackStandIn[]>;
+/**
+ * Queues the delete of one placeholder. Once approved, the result is the list as it reads afterwards.
+ *
+ * The rule pointing at it goes with it. A record the app opened for one branch refuses that branch as
+ * it goes, so no second one opens for it; a record naming no branch refuses nothing, and the next
+ * pass may open one at whatever grain the day reads.
+ */
+export declare const timetrackRemoveStandIn: (id: string) => Promise<TimetrackQueued>;
+/**
+ * Queues another name for one placeholder. Once approved, the result is the list as it reads afterwards.
+ *
+ * Only the name changes. The days it holds and the rules that name it stay, which is what a delete
+ * and a fresh record would lose.
+ */
+export declare const timetrackRenameStandIn: (options: {
+    id: string;
+    name: string;
+}) => Promise<TimetrackQueued>;
+/**
+ * Queues the merge of one open placeholder into another. Once approved, the result is the list as it
+ * reads afterwards. The kept one takes the days and the rules of both.
+ */
+export declare const timetrackMergeStandIn: (options: {
+    id: string;
+    into: string;
+}) => Promise<TimetrackQueued>;
+/**
+ * Queues the resolve of one placeholder to a Jira issue, as the user's pick in the app does. A resolved
+ * one moves to the new issue. The app checks both exist before it queues; once approved, the result is
+ * the list as it reads afterwards.
+ */
+export declare const timetrackResolveStandIn: (options: {
+    id: string;
+    issueKey: string;
+}) => Promise<TimetrackQueued>;
+/**
+ * Plans the cut of one placeholder into one per directory it turned out to cover, and writes nothing.
+ *
+ * The commits come from the caller: one
+ * collected before Timetrack read file paths carries none, so only `git log --name-only` can say.
+ * A checkout whose commits name more directories than a grain can hold has no automatic reading,
+ * and `paths` is how the user picks which of them are the pieces.
+ */
+export declare const timetrackSplitStandIn: (options: {
+    id: string;
+    branch: string;
+    commits: readonly TimetrackWorkCommit[];
+    /** The checkout the directories are in, for a record that names none of its own. */
+    repoPath?: string;
+    /** The projects the checkout declares, relative to it. They are the grain a piece is cut to. */
+    projectRoots: readonly string[];
+    /** The directories the user picked as the pieces. Empty lets the automatic reading answer. */
+    paths: readonly string[];
+    /** The directory that takes every day of the record no commit claims. */
+    claim?: string;
+}) => Promise<TimetrackStandInSplit>;
+/** Queues the split `timetrackSplitStandIn` planned, with the same options. */
+export declare const timetrackApplyStandInSplit: (options: Parameters<typeof timetrackSplitStandIn>[0]) => Promise<TimetrackQueued>;
+/** Where a write this caller queued stands, and what it answered once the user approved it. */
+export declare const timetrackApprovalStatus: (id: string) => Promise<TimetrackApprovalStatus>;
+/** One write that still waits in the app. `running` was approved and is being carried out. */
+export type TimetrackWaitingApproval = {
+    approvalId: string;
+    state: 'queued' | 'running';
+    op: string;
+    client?: string;
+    askedAtMs: number;
+    summary: string;
+};
+/** The writes that wait in the app now, from every caller, in the order its queue panel lists them. */
+export declare const timetrackApprovals: () => Promise<TimetrackWaitingApproval[]>;
+/**
+ * Rejects one write that waits, as the user's Reject press does, and answers at once. The app refuses an
+ * item that no longer waits. There is no approving counterpart: only the user approves, in the app.
+ */
+export declare const timetrackRejectApproval: (id: string) => Promise<TimetrackApprovalStatus>;
+/** What an auto mode ask is about: an open stand-in, or the unnamed context behind a band. */
+export type TimetrackAutoModeSubject = {
+    kind: 'stand-in';
+    standInId: string;
+} | {
+    kind: 'context';
+    contextId: string;
+};
+/** What `timetrackAskAutoMode` queued. `asking` means an ask about it already waited or ran. */
+export type TimetrackAutoModeAsk = {
+    status: 'queued' | 'asking';
+    day: string;
+    subject: TimetrackAutoModeSubject;
+    label: string;
+};
+/**
+ * Asks auto mode about one subject of a day again, as the app's "Ask auto mode again" does, and answers
+ * at once with what it queued. The new answer replaces the stored one later; it writes nothing to Jira or
+ * Tempo, and whatever it queues waits for the user's approval as auto mode's own does.
+ */
+export declare const timetrackAskAutoMode: (options: {
+    day: string;
+    subject: TimetrackAutoModeSubject;
+}) => Promise<TimetrackAutoModeAsk>;