@pome-sh/checks 0.1.0

package/dist/_types/twin-gmail/src/types.d.ts

@@ -0,0 +1,150 @@
+import type { TwinDatabase } from "../../sdk/db.js";
+export type GmailTwinDatabase = TwinDatabase;
+export type DeliveryMode = "sender-only" | "seeded-mailboxes";
+export type SeedLabel = {
+    id?: string;
+    name: string;
+    color?: {
+        textColor?: string;
+        backgroundColor?: string;
+    };
+};
+export type SeedAttachment = {
+    filename: string;
+    mimeType?: string;
+    disposition?: "attachment" | "inline";
+    contentId?: string;
+    data: string;
+};
+export type SeedMessage = {
+    id?: string;
+    threadId?: string;
+    raw?: string;
+    from?: string;
+    to?: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject?: string;
+    text?: string;
+    html?: string;
+    date?: string;
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string[];
+    labels?: string[];
+    attachments?: SeedAttachment[];
+};
+export type SeedDraft = Omit<SeedMessage, "labels"> & {
+    id?: string;
+};
+export type SeedFilter = {
+    id?: string;
+    criteria?: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        query?: string;
+        negatedQuery?: string;
+        hasAttachment?: boolean;
+        excludeChats?: boolean;
+        size?: number;
+        sizeComparison?: "larger" | "smaller";
+    };
+    action?: {
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+        forward?: string;
+    };
+};
+export type SeedSendAs = {
+    sendAsEmail: string;
+    displayName?: string;
+    replyToAddress?: string;
+    isPrimary?: boolean;
+    isDefault?: boolean;
+    verificationStatus?: "accepted" | "pending";
+};
+export type SeedMailbox = {
+    email: string;
+    displayName?: string;
+    labels?: SeedLabel[];
+    messages?: SeedMessage[];
+    drafts?: SeedDraft[];
+    filters?: SeedFilter[];
+    forwardingAddresses?: Array<{
+        forwardingEmail: string;
+        verificationStatus?: "accepted" | "pending";
+    }>;
+    sendAs?: SeedSendAs[];
+};
+export type GmailStateSeed = {
+    primaryMailbox: SeedMailbox;
+    mailboxes?: SeedMailbox[];
+    deliveryMode?: DeliveryMode;
+    clock?: string;
+    faults?: import("./faults.js").GmailFault[];
+};
+export type MessageRow = {
+    mailbox_id: number;
+    id: string;
+    thread_id: string;
+    rfc_message_id: string;
+    internal_date: number;
+    sent_at: string;
+    from_address: string;
+    to_json: string;
+    cc_json: string;
+    bcc_json: string;
+    delivered_to: string;
+    subject: string;
+    normalized_subject: string;
+    snippet: string;
+    text_body: string;
+    html_body: string;
+    headers_json: string;
+    size_estimate: number;
+};
+export type DraftRow = {
+    mailbox_id: number;
+    id: string;
+    message_id: string;
+    created_at: string;
+    updated_at: string;
+};
+export type HistoryEvent = {
+    id: string;
+    mailboxEmail: string;
+    messageId: string | null;
+    threadId: string | null;
+    type: string;
+    labelIds: string[];
+    timestamp: string;
+};
+export type GmailIdentity = {
+    email: string;
+};
+export type SemanticMessage = {
+    id: string;
+    threadId: string;
+    rfcMessageId: string;
+    internalDate: number;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    subject: string;
+    snippet: string;
+    text: string;
+    html: string;
+    sizeEstimate: number;
+    labelIds: string[];
+    attachments: Array<{
+        id: string;
+        filename: string;
+        mimeType: string;
+        disposition: string;
+        contentId: string | null;
+        sha256: string;
+        size: number;
+    }>;
+};

package/dist/_types/twin-linear/src/check-kind.d.ts

@@ -0,0 +1,3 @@
+import type { CheckDefinition } from "../../sdk/checks.js";
+import type { LinearCheckState } from "./check-state.js";
+export type Check<TArgs extends Record<string, string>> = CheckDefinition<LinearCheckState, TArgs>;

package/dist/_types/twin-linear/src/check-state.d.ts

@@ -0,0 +1,123 @@
+import { type CheckOutcome } from "../../sdk/checks.js";
+export interface LinearCheckStateTeam {
+    id?: string;
+    key?: string;
+    name?: string;
+}
+export interface LinearCheckStateWorkflowState {
+    id?: string;
+    teamId?: string;
+    name?: string;
+    type?: string;
+}
+export interface LinearCheckStateLabel {
+    id?: string;
+    teamId?: string;
+    name?: string;
+}
+export interface LinearCheckStateIssue {
+    id?: string;
+    identifier?: string;
+    number?: number;
+    teamId?: string;
+    title?: string;
+    estimate?: number | null;
+    stateId?: string;
+    assigneeId?: string;
+    archivedAt?: string | null;
+    labelIds?: string[];
+}
+export interface LinearCheckStateComment {
+    id?: string;
+    issueId?: string;
+    parentId?: string | null;
+    userId?: string;
+    body?: string;
+}
+export interface LinearCheckStateUser {
+    id?: string;
+    email?: string;
+    name?: string;
+    displayName?: string;
+}
+export interface LinearCheckState {
+    teams?: LinearCheckStateTeam[] | null;
+    workflowStates?: LinearCheckStateWorkflowState[] | null;
+    labels?: LinearCheckStateLabel[] | null;
+    issues?: LinearCheckStateIssue[] | null;
+    comments?: LinearCheckStateComment[] | null;
+    users?: LinearCheckStateUser[] | null;
+    exportBounds?: {
+        truncatedCollections?: string[];
+    } | null;
+}
+/**
+ * twin-github's `Resolved<T>` with one field added.
+ *
+ * github's resolvers always FAIL on a miss and twin-slack's always SKIP. Linear
+ * needs both from the same resolver, because a miss inside a truncated
+ * collection is evidence of a partial export while a miss in a complete one is
+ * evidence about the examinee. Carrying the disposition on the value is what
+ * stops every call site from re-deciding it — and re-deciding it wrongly is how
+ * a do-nothing agent scores 100% on task 26.
+ */
+export type Resolved<T> = {
+    found: T;
+    path: string;
+} | {
+    missing: string;
+    skip: boolean;
+    searched?: string;
+};
+/** The exported collections a pointer can address (F-1197). Named because seven
+ *  declarations reach for them. */
+export declare const ISSUES_PATH: string;
+export declare const COMMENTS_PATH: string;
+export declare const LABELS_PATH: string;
+export declare const WORKFLOW_STATES_PATH: string;
+export declare const USERS_PATH: string;
+/**
+ * A pointer at `key` on the row `base` addresses, falling back to the row when
+ * the export does not carry that key (F-1197).
+ *
+ * The fallback is the whole point and it is not defensive padding. An UNSET
+ * estimate and an ABSENT assignee are both real, common, and exactly the
+ * verdicts a reader wants to inspect — and a pointer at a key the row does not
+ * have resolves to nothing, which would strip the affordance from precisely
+ * those rows. Widening to the row keeps the citation honest (it is where the
+ * check looked) and resolvable (the row is there).
+ */
+export declare function fieldPath(base: string, row: object, key: string): string;
+/** The one place an unresolved selector becomes an outcome.
+ *
+ *  F-1197 — it also carries the citation, so the rule "a refusal names where it
+ *  looked" is written once rather than at fourteen call sites. */
+export declare function unresolved(r: {
+    missing: string;
+    skip: boolean;
+    searched?: string;
+}): CheckOutcome;
+export declare function isTruncated(state: LinearCheckState, collection: string): boolean;
+/**
+ * The issue an assertion is about, by exact title, scoped to one team.
+ *
+ * Exact rather than case-insensitive: the task names the title it seeded or
+ * asked for, and a case-folding match would let an examinee half-comply.
+ */
+export declare function resolveIssue(state: LinearCheckState, teamKey: string, title: string): Resolved<LinearCheckStateIssue>;
+/** Trap 1: `stateId` → the team's own workflow-state row. */
+export declare function resolveWorkflowStateName(state: LinearCheckState, issue: LinearCheckStateIssue): Resolved<string>;
+/**
+ * Trap 2: `labelIds` → catalog names, lowercased.
+ *
+ * Case-insensitive because the legacy rule's `eqi` was, and because a label an
+ * examinee creates is prose it retyped.
+ */
+export declare function resolveLabelNames(state: LinearCheckState, issue: LinearCheckStateIssue): Resolved<Set<string>>;
+export declare function resolveComments(state: LinearCheckState, issue: LinearCheckStateIssue): Resolved<LinearCheckStateComment[]>;
+/**
+ * Every spelling of a user the legacy `linear.issue-assignee` rule accepted —
+ * email, name, displayName — in that order, so a reason string names the most
+ * specific one first.
+ */
+export declare function resolveUserLabels(state: LinearCheckState, id: string | undefined): string[];

package/dist/_types/twin-linear/src/checks.d.ts

@@ -0,0 +1,29 @@
+export type { Check } from "./check-kind.js";
+export type { LinearCheckState, LinearCheckStateComment, LinearCheckStateIssue, LinearCheckStateLabel, LinearCheckStateTeam, LinearCheckStateUser, LinearCheckStateWorkflowState, } from "./check-state.js";
+export declare const LINEAR_CHECKS: readonly [import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+    state: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+    label: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+    estimate: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+    user: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+    needle: string;
+}>, import("./check-kind.js").Check<{
+    title: string;
+    team: string;
+}>, import("./check-kind.js").Check<Record<string, never>>];

package/dist/_types/twin-linear/src/seed.d.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { type LinearStateSeed } from "./types.js";
+export declare const linearSeedSchema: z.ZodObject<{
+    clock: z.ZodDefault<z.ZodString>;
+    defaultSid: z.ZodDefault<z.ZodString>;
+    baseUrl: z.ZodDefault<z.ZodString>;
+    strictScopes: z.ZodDefault<z.ZodBoolean>;
+    organization: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        urlKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    users: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        email: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        name: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        active: z.ZodDefault<z.ZodBoolean>;
+        admin: z.ZodDefault<z.ZodBoolean>;
+        app: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    teams: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        private: z.ZodDefault<z.ZodBoolean>;
+        states: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodEnum<{
+                backlog: "backlog";
+                unstarted: "unstarted";
+                started: "started";
+                completed: "completed";
+                canceled: "canceled";
+            }>>;
+            position: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        color: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        team: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        state: z.ZodDefault<z.ZodEnum<{
+            started: "started";
+            completed: "completed";
+            canceled: "canceled";
+            planned: "planned";
+        }>>;
+        team: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    cycles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        team: z.ZodString;
+        name: z.ZodString;
+        number: z.ZodOptional<z.ZodNumber>;
+        startsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        endsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        team: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        priority: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+        state: z.ZodOptional<z.ZodString>;
+        assignee: z.ZodOptional<z.ZodString>;
+        creator: z.ZodOptional<z.ZodString>;
+        delegate: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        cycle: z.ZodOptional<z.ZodString>;
+        parent: z.ZodOptional<z.ZodString>;
+        estimate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        dueDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    comments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        issue: z.ZodString;
+        body: z.ZodString;
+        parent: z.ZodOptional<z.ZodString>;
+        user: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    documents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        slug: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        team: z.ZodOptional<z.ZodString>;
+        issue: z.ZodOptional<z.ZodString>;
+        cycle: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        creator: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    oauthApps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecret: z.ZodString;
+        name: z.ZodString;
+        redirectUris: z.ZodArray<z.ZodString>;
+        scopes: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+        actor: z.ZodDefault<z.ZodEnum<{
+            user: "user";
+            app: "app";
+        }>>;
+        assignable: z.ZodDefault<z.ZodBoolean>;
+        mentionable: z.ZodDefault<z.ZodBoolean>;
+        appUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    tokens: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        token: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            personal: "personal";
+            oauth_access: "oauth_access";
+            client_credentials: "client_credentials";
+        }>>;
+        user: z.ZodOptional<z.ZodString>;
+        app: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+        actor: z.ZodOptional<z.ZodEnum<{
+            user: "user";
+            app: "app";
+        }>>;
+        sid: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    webhooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        resourceTypes: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+        team: z.ZodOptional<z.ZodString>;
+        allPublicTeams: z.ZodOptional<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ParsedLinearStateSeed = z.output<typeof linearSeedSchema>;
+export declare function parseSeed(input: unknown): ParsedLinearStateSeed;
+/**
+ * `Record<string, string | undefined>` rather than `NodeJS.ProcessEnv`, which is
+ * structurally the same thing but an AMBIENT global. This signature is vendored
+ * into `@pome-sh/checks`'s published declarations, and an ambient reference there
+ * makes a consumer's `tsc` fail with TS2503 unless they happen to have
+ * `@types/node` installed — a dependency this package should not impose to
+ * describe a plain string map.
+ */
+export declare function loadSeedFromEnv(env?: Record<string, string | undefined>): ParsedLinearStateSeed;
+/** Multi-issue agent world: ENG team, admin+dev, triage/progress/done issues. */
+export declare function defaultSeedState(): LinearStateSeed;