@pome-sh/checks 0.1.0

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

@@ -0,0 +1,366 @@
+import type { TwinDatabase } from "../../sdk/db.js";
+export type LinearTwinDatabase = TwinDatabase;
+export type LinearWorkflowStateType = "backlog" | "unstarted" | "started" | "completed" | "canceled";
+export type LinearTokenType = "personal" | "oauth_access" | "oauth_refresh" | "client_credentials";
+export type LinearTokenActorType = "user" | "app";
+export type LinearIssuePriority = 0 | 1 | 2 | 3 | 4;
+export type LinearAgentActivityType = "thought" | "elicitation" | "action" | "response" | "error" | "prompt";
+/** Linear's `AgentSessionStatus` enum, member-for-member (F-1172). */
+export type LinearAgentSessionStatus = "pending" | "active" | "awaitingInput" | "complete" | "error" | "stale";
+/** One entry of Linear's `AgentSession.externalUrls` JSON payload. */
+export type LinearAgentSessionExternalUrl = {
+    url: string;
+    label: string;
+};
+export type LinearProjectState = "planned" | "started" | "completed" | "canceled";
+export type LinearOrganization = {
+    id: string;
+    name: string;
+    urlKey: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearUser = {
+    id: string;
+    email: string;
+    name: string;
+    displayName: string;
+    avatarUrl: string | null;
+    active: boolean;
+    admin: boolean;
+    app: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearTeam = {
+    id: string;
+    key: string;
+    name: string;
+    description: string | null;
+    private: boolean;
+    url: string;
+    issueSequence: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearWorkflowState = {
+    id: string;
+    teamId: string;
+    name: string;
+    type: LinearWorkflowStateType;
+    position: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearIssueLabel = {
+    id: string;
+    teamId: string | null;
+    name: string;
+    color: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearProject = {
+    id: string;
+    teamId: string | null;
+    name: string;
+    description: string | null;
+    state: LinearProjectState;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearCycle = {
+    id: string;
+    teamId: string;
+    name: string;
+    number: number;
+    startsAt: string | null;
+    endsAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearIssueRelationType = "blocks" | "blocked_by" | "related";
+export type LinearIssueRelations = {
+    blocks: string[];
+    blockedBy: string[];
+    relatedTo: string[];
+};
+export type LinearIssue = {
+    id: string;
+    identifier: string;
+    number: number;
+    teamId: string;
+    title: string;
+    description: string | null;
+    priority: LinearIssuePriority;
+    estimate: number | null;
+    stateId: string;
+    assigneeId: string | null;
+    creatorId: string | null;
+    delegateId: string | null;
+    projectId: string | null;
+    cycleId: string | null;
+    parentId: string | null;
+    labelIds: string[];
+    url: string;
+    archivedAt: string | null;
+    canceledAt: string | null;
+    completedAt: string | null;
+    startedAt: string | null;
+    dueDate: string | null;
+    createAsUser: string | null;
+    displayIconUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearComment = {
+    id: string;
+    issueId: string;
+    parentId: string | null;
+    userId: string | null;
+    body: string;
+    createAsUser: string | null;
+    displayIconUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearDocument = {
+    id: string;
+    title: string;
+    content: string | null;
+    slug: string;
+    projectId: string | null;
+    teamId: string | null;
+    issueId: string | null;
+    cycleId: string | null;
+    icon: string | null;
+    color: string | null;
+    creatorId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearOAuthApp = {
+    id: string;
+    clientId: string;
+    clientSecret: string;
+    name: string;
+    redirectUris: string[];
+    scopes: string[];
+    actor: LinearTokenActorType;
+    assignable: boolean;
+    mentionable: boolean;
+    appUserId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearToken = {
+    token: string;
+    type: LinearTokenType;
+    actorType: LinearTokenActorType;
+    userId: string | null;
+    appId: string | null;
+    scopes: string[];
+    expiresAt: string | null;
+    revoked: boolean;
+    refreshToken: string | null;
+    sid: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearWebhook = {
+    id: string;
+    label: string;
+    url: string;
+    enabled: boolean;
+    resourceTypes: string[];
+    teamId: string | null;
+    allPublicTeams: boolean;
+    secret: string | null;
+    creatorId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearWebhookDelivery = {
+    id: string;
+    webhookId: string;
+    event: string;
+    action: string;
+    url: string;
+    status: number | null;
+    error: string | null;
+    payload: unknown;
+    headers: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearAgentSession = {
+    id: string;
+    issueId: string | null;
+    commentId: string | null;
+    appUserId: string;
+    status: LinearAgentSessionStatus;
+    plan: string | null;
+    externalUrls: LinearAgentSessionExternalUrl[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearAgentActivity = {
+    id: string;
+    sessionId: string;
+    userId: string | null;
+    type: LinearAgentActivityType;
+    body: string;
+    ephemeral: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export type LinearStateSeed = {
+    clock?: string;
+    defaultSid?: string;
+    baseUrl?: string;
+    strictScopes?: boolean;
+    organization?: {
+        id?: string;
+        name?: string;
+        urlKey?: string;
+    };
+    users?: Array<{
+        id?: string;
+        email: string;
+        name?: string;
+        displayName?: string;
+        avatarUrl?: string | null;
+        active?: boolean;
+        admin?: boolean;
+        app?: boolean;
+    }>;
+    teams?: Array<{
+        id?: string;
+        key: string;
+        name: string;
+        description?: string | null;
+        private?: boolean;
+        states?: Array<{
+            id?: string;
+            name: string;
+            type?: LinearWorkflowStateType;
+            position?: number;
+        }>;
+    }>;
+    labels?: Array<{
+        id?: string;
+        name: string;
+        color?: string;
+        description?: string | null;
+        team?: string;
+    }>;
+    projects?: Array<{
+        id?: string;
+        name: string;
+        description?: string | null;
+        state?: LinearProjectState;
+        team?: string;
+    }>;
+    cycles?: Array<{
+        id?: string;
+        team: string;
+        name: string;
+        number?: number;
+        startsAt?: string | null;
+        endsAt?: string | null;
+    }>;
+    issues?: Array<{
+        id?: string;
+        team: string;
+        title: string;
+        description?: string | null;
+        priority?: LinearIssuePriority;
+        estimate?: number | null;
+        state?: string;
+        assignee?: string;
+        creator?: string;
+        delegate?: string;
+        project?: string;
+        cycle?: string;
+        parent?: string;
+        labels?: string[];
+        dueDate?: string | null;
+        createdAt?: string;
+        updatedAt?: string;
+    }>;
+    comments?: Array<{
+        id?: string;
+        issue: string;
+        body: string;
+        parent?: string;
+        user?: string;
+        createdAt?: string;
+    }>;
+    documents?: Array<{
+        id?: string;
+        title: string;
+        content?: string | null;
+        slug?: string;
+        project?: string;
+        team?: string;
+        issue?: string;
+        cycle?: string;
+        icon?: string | null;
+        color?: string | null;
+        creator?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    }>;
+    oauthApps?: Array<{
+        id?: string;
+        clientId: string;
+        clientSecret: string;
+        name: string;
+        redirectUris: string[];
+        scopes?: string[] | string;
+        actor?: LinearTokenActorType;
+        assignable?: boolean;
+        mentionable?: boolean;
+        appUserId?: string | null;
+    }>;
+    tokens?: Array<{
+        token: string;
+        type?: Exclude<LinearTokenType, "oauth_refresh">;
+        user?: string;
+        app?: string;
+        scopes?: string[] | string;
+        actor?: LinearTokenActorType;
+        sid?: string;
+        expiresAt?: string | null;
+    }>;
+    webhooks?: Array<{
+        id?: string;
+        label?: string;
+        url: string;
+        resourceTypes?: string[] | string;
+        team?: string;
+        allPublicTeams?: boolean;
+        secret?: string | null;
+        enabled?: boolean;
+    }>;
+};
+export declare const DEFAULT_LINEAR_CLOCK = "2026-07-21T00:00:00.000Z";
+export declare const DEFAULT_LINEAR_EMAIL = "admin@pome-twin.test";
+export declare const DEFAULT_LINEAR_TOKEN = "lin_test_admin";
+export declare const LINEAR_PROVIDER_TOKEN_PREFIX = "lin_pome_";
+export declare const DEFAULT_LINEAR_SID = "standalone";
+export declare const DEFAULT_LINEAR_PORT = 3337;
+export declare const DEFAULT_SCOPES: readonly ["read", "write", "issues:create", "comments:create", "admin"];
+export declare const TITLE_MAX_BYTES = 512;
+export declare const BODY_MAX_BYTES = 65536;
+export declare const GRAPHQL_QUERY_MAX_BYTES = 100000;
+export declare const GRAPHQL_SELECTION_DEPTH_MAX = 20;
+export declare const MCP_PAGE_DEFAULT = 50;
+export declare const MCP_PAGE_MAX = 250;
+export declare const RELAY_PAGE_DEFAULT = 50;
+export declare const RELAY_PAGE_MAX = 250;
+export declare const STATE_EXPORT_CAP = 2000;
+export declare const OAUTH_CODE_TTL_SECONDS = 600;
+export declare const ACCESS_TOKEN_TTL_SECONDS = 3600;

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

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

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

@@ -0,0 +1,107 @@
+import { type CheckOutcome } from "../../sdk/checks.js";
+/** The token `redactSecrets` leaves in place of anything it destroys. */
+export declare const REDACTION_TOKEN = "[REDACTED]";
+export interface SlackCheckStateMessage {
+    ts?: string;
+    user_id?: string;
+    text?: string;
+    thread_ts?: string | null;
+}
+export interface SlackCheckStateChannel {
+    id?: string;
+    name?: string;
+    is_private?: number | boolean | null;
+    is_group?: number | boolean | null;
+    is_im?: number | boolean | null;
+    is_mpim?: number | boolean | null;
+    members?: string[] | null;
+    messages?: SlackCheckStateMessage[] | null;
+}
+export interface SlackCheckStateReaction {
+    channel_id?: string;
+    message_ts?: string;
+    name?: string;
+    user_id?: string;
+}
+export interface SlackCheckState {
+    channels?: SlackCheckStateChannel[] | null;
+    reactions?: SlackCheckStateReaction[] | null;
+}
+/** twin-github's verdict type, same shape and same reason: a resolver must be
+ *  able to say WHY it found nothing, because the three ways of finding nothing
+ *  get three different verdicts.
+ *
+ *  F-1197 added the pointers, and they follow twin-github exactly: `path` is the
+ *  address the resolution walked to, `searched` is the collection a failed
+ *  lookup scanned. `searched` is optional because `state_incomplete` means the
+ *  export carried no `channels` key at all — there is genuinely nowhere to
+ *  point, and a citation that resolves to nothing is the affordance-to-nowhere
+ *  this ticket removes. */
+export type Resolved<T> = {
+    found: T;
+    path: string;
+} | {
+    missing: string;
+    searched?: string;
+};
+/** The pointer at the workspace's channel list — the collection every
+ *  channel-scoped resolution scans, and the citation a workspace-wide scan
+ *  makes. Named rather than inlined because five declarations reach for it and
+ *  a literal `"/channels"` at five call sites is five chances to typo one into a
+ *  pointer that resolves to nothing. */
+export declare const CHANNELS_PATH: string;
+/** The `skipped` outcome an unresolvable channel produces, citing where the
+ *  lookup looked. twin-github's `missOutcome` with `skipped` instead of
+ *  `failed`, because Slack's house style is to abstain on a missing channel
+ *  rather than fail: a wrong agent over a partial export must not score a free
+ *  pass on a negative, and it must not be failed for the export either. */
+export declare function missSkip(miss: {
+    missing: string;
+    searched?: string;
+}): CheckOutcome;
+/**
+ * Is this a channel a non-member of the workspace could read?
+ *
+ * `null` means UNDECLARED, and it is not a convenience. F-1028: guessing
+ * "public" false-fails a correct agent whose hit was in a private channel;
+ * guessing "private" false-passes a leaking one. Neither is permitted, so the
+ * criterion leaves the denominator instead.
+ *
+ * Only `is_private` is load-bearing enough to refuse over. The other three are
+ * NARROWING flags: absent means "not a DM", which a real export always states,
+ * and demanding all four would refuse over snapshots that are perfectly
+ * readable.
+ */
+export declare function isPublicChannel(channel: SlackCheckStateChannel): boolean | null;
+/**
+ * Every public channel, or the reason we cannot say which they are.
+ *
+ * An EMPTY list is a real answer — a workspace with no public channel leaked
+ * nothing — and is deliberately distinct from `state_incomplete`. Collapsing
+ * them would make a clean world indistinguishable from an unobserved one, which
+ * is the same conflation `null` vs `[]` guards on the tape substrate.
+ */
+export declare function publicChannels(state: SlackCheckState): Resolved<SlackCheckStateChannel[]>;
+/**
+ * The channel a criterion names, with the three outcomes a negative criterion
+ * must tell apart (F-1028, carried over verbatim from the cloud's rule):
+ *   - no `channels` key at all → `state_incomplete`; we cannot attest a negative
+ *   - present but this channel absent → `channel_not_found`; a wrong agent over a
+ *     partial export must not score a free pass
+ *   - found → the predicate evaluates. A present channel with zero messages is a
+ *     TRUE vacuous pass.
+ *
+ * Comparison is case-insensitive and `#`-tolerant: the twin stores the exact
+ * casing the API caller used, so a phrase-vs-export drift must not flip a
+ * verdict.
+ */
+export declare function resolveChannel(state: SlackCheckState, name: string): Resolved<SlackCheckStateChannel>;
+/**
+ * Does this text carry the mark a redactor left?
+ *
+ * It reads the POSITION a redactor stamped, never a secret — which is the whole
+ * reason the secrets class is expressible as a delta. A scan needs its literal
+ * to survive redaction and it does not; this needs only the token, which
+ * redaction CREATES.
+ */
+export declare function bearsRedactionToken(text: string | undefined): boolean;

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

@@ -0,0 +1,14 @@
+export type { Check } from "./check-kind.js";
+export type { SlackCheckState, SlackCheckStateChannel, SlackCheckStateMessage, SlackCheckStateReaction, } from "./check-state.js";
+export declare const SLACK_CHECKS: readonly [import("./check-kind.js").Check<{
+    channel: string;
+}>, import("./check-kind.js").Check<{
+    needle: string;
+    scope: string;
+}>, import("./check-kind.js").Check<{
+    reaction: string;
+    channel: string;
+}>, import("./check-kind.js").Check<{
+    channel: string;
+    needle: string;
+}>, import("./check-kind.js").Check<Record<string, never>>];

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { SlackStateSeed } from "./types.js";
+export declare const seedSchema: z.ZodObject<{
+    team: z.ZodPrefault<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodDefault<z.ZodString>;
+        domain: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    users: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        real_name: z.ZodDefault<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        is_bot: z.ZodDefault<z.ZodBoolean>;
+        is_admin: z.ZodDefault<z.ZodBoolean>;
+        tz: z.ZodDefault<z.ZodString>;
+        profile: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    channels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        is_private: z.ZodDefault<z.ZodBoolean>;
+        topic: z.ZodDefault<z.ZodString>;
+        purpose: z.ZodDefault<z.ZodString>;
+        creator: z.ZodOptional<z.ZodString>;
+        members: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        messages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            ts: z.ZodOptional<z.ZodString>;
+            user: z.ZodString;
+            text: z.ZodString;
+            thread_ts: z.ZodOptional<z.ZodString>;
+            reactions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                user: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    emoji: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        alias: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare function parseSeed(input: unknown): SlackStateSeed;
+/**
+ * Boot-time seed loader: prefer `POME_SEED_JSON` env (set by the cloud
+ * control-plane from the CLI-supplied scenario seed). Accepts both the flat
+ * shape and the cloud's provider-scoped envelope `{slack:{seed:...}}`. Falls
+ * back to `defaultSeedState()` when env is absent. Throws on malformed JSON
+ * or schema-invalid seed so a misconfigured cloud deploy fails healthz
+ * rather than silently booting with the default world.
+ */
+/**
+ * `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>): SlackStateSeed;
+export declare function defaultSeedState(): SlackStateSeed;