@rackbops/ac-plugin-contract 2.0.0-alpha.33

package/dist/host-api.d.ts

@@ -0,0 +1,365 @@
+/**
+ * `HostApi` is the service surface the host passes to `createPlugin(host)` on the server, and the
+ * `@ac/host` module the shell exposes to frontend bundles in the browser (design.md §3). This is
+ * the v1 shape; the server implementation landed in #28, with `sidecar` real as of #29's proxy,
+ * `jobs` as of #31's scheduler, `agent` as of E4, and `github` real as of #127's Octokit client; the
+ * browser side lands in #32. Methods are added additively — a breaking change bumps
+ * `HOST_API_VERSION`.
+ */
+import type { Octokit } from "@octokit/rest";
+import type { HttpMethod } from "./manifest.js";
+import type { AgentCallOutcome, JobMachineRun, MachineView } from "./views.js";
+/** A typed, per-plugin settings accessor (backed by the host's settings overlay). */
+export interface SettingsService {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+}
+/** Per-plugin durable storage: a SQLite table scoped to the plugin, with atomic JSON helpers. */
+export interface StorageService {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Register/trigger the plugin's contributed jobs and read their last result. */
+export interface JobsService {
+    /** Run a contributed job now (the manual-trigger endpoint). For a `runOn: "agent"` job this resolves
+     *  once every currently paired machine has either run or been queued. */
+    trigger(jobId: string): Promise<void>;
+    /** The last run of a job, if it has run — for an agent job, the newest recorded run across every
+     *  machine. */
+    lastRun(jobId: string): Promise<{
+        startedAt: string;
+        ok: boolean;
+    } | undefined>;
+    /** One row per relevant machine (#51): a single null-id row for a host job, one row per currently
+     *  paired machine for an agent job. */
+    machineRuns(jobId: string): Promise<JobMachineRun[]>;
+    /** #78: the SAME shape as `machineRuns`, for an OTHER plugin's declared job -- `machineRuns` stays
+     *  scoped to the calling plugin's own jobs; this is the needs-attention rollup's in-process read of
+     *  every OTHER loaded plugin's job health, so `overview`'s `/attention` route never has to make an
+     *  HTTP call back into its own host. Discloses nothing `GET /api/jobs/:pluginId/:jobId/runs`
+     *  doesn't already serve publicly -- just a non-HTTP path to the same data. Optional: only
+     *  `overview` calls it today. */
+    machineRunsOf?(pluginId: string, jobId: string): Promise<JobMachineRun[]>;
+}
+/** #78: every loaded in-process plugin's own declared jobs -- lets the needs-attention rollup
+ *  discover what to poll via `jobs.machineRunsOf` without a second manifest fetch or an HTTP
+ *  self-loop. Host-internal discovery only (unlike `PluginView`, never served over HTTP as its own
+ *  route); optional on `HostApi` since only `overview` uses it. */
+export interface PluginJobsService {
+    list(): {
+        pluginId: string;
+        jobs: JobDeclaration[];
+    }[];
+}
+/** The subset of `JobContribution` (`manifest.ts`) the rollup needs -- id, schedule metadata are
+ *  irrelevant to it, so this stays a narrow projection rather than the full manifest shape. */
+export interface JobDeclaration {
+    id: string;
+    runOn: "host" | "agent";
+}
+/** The typed event bus (e.g. `issue.changed`, `job.finished`, `artifact.rendered`). */
+export interface EventsService {
+    emit(type: string, payload: unknown): void;
+    /** Subscribe; returns an unsubscribe function. */
+    on(type: string, handler: (payload: unknown) => void): () => void;
+}
+/** One shared, rate-limit-aware GitHub client (Octokit; PAT from env, #127). Consumers make every
+ *  GitHub call through `octokit()` rather than constructing a second client. */
+export interface GithubService {
+    /** The authenticated login, cached. */
+    viewer(): Promise<string>;
+    /** The one shared Octokit REST client — consumers make all GitHub calls through this. */
+    octokit(): Octokit;
+    /** Remaining primary-rate-limit budget from the last response's headers, or undefined before any
+     *  call. */
+    rateLimit(): {
+        remaining: number;
+        limit: number;
+        resetAt: string;
+    } | undefined;
+}
+/**
+ * Call a paired host-agent verb, or list the paired machines (#50). `HostApi.agent` is scoped per
+ * plugin the same way `storage`/`settings` are (`host-factory.ts`) -- the plugin id a call carries
+ * is the host's own, never a value the plugin supplies, so a plugin can only ever act as itself and
+ * cannot reach pairing or grants through this surface at all. Streaming (`GET /v1/jobs/:id/events`)
+ * and the `runOn: "agent"` job fan-out are #51/#54.
+ */
+export interface AgentService {
+    /** The ids of the machines currently paired with the console. */
+    machines(): Promise<string[]>;
+    /** The paired machines, with their current grants. */
+    list(): Promise<MachineView[]>;
+    /** Call one of this plugin's declared capabilities on a paired machine's agent. */
+    call<T = unknown>(machineId: string, method: "GET" | "POST", path: string, body?: unknown, opts?: {
+        /** How long to wait for the agent's response headers (undici's headersTimeout; its default is
+         *  300 s). A long-running verb -- a scan -- passes the verb's own limit plus a margin, so the
+         *  agent's own timeout answer arrives before the console gives up. */
+        timeoutMs?: number;
+    }): Promise<AgentCallOutcome<T>>;
+    /**
+     * Open a paired machine's job event stream (`GET /v1/jobs/:jobId/events`, #54) and relay it into a
+     * new host task: every agent `line` frame becomes a `task.log`, the `done` frame finishes it --
+     * the tasks drawer streams the machine's job with no new UI (decision 12/20). Resolves with the new
+     * task's id once the stream is confirmed open (the agent answered `200`); the relay itself then runs
+     * detached and can never surface here. Rejects (starting no task) on an invalid `jobId`, an unknown
+     * machine, or any non-`200` response from the agent (a `404` unknown job, a `403` refusal, ...) --
+     * the same failure shapes `call` throws for a bad path, surfaced the same way.
+     */
+    streamJob(machineId: string, jobId: string, opts: {
+        label: string;
+    }): Promise<{
+        taskId: string;
+    }>;
+}
+/** Proxy to a sidecar plugin's HTTP surface (the host handles health + base URL). */
+export interface SidecarService {
+    /** The base URL the host proxies to for a sidecar plugin. */
+    baseUrl(pluginId: string): string;
+}
+/** Register a confirm-gated action; the shell builds its button + modal from the manifest data. */
+export interface ActionsService {
+    register(action: {
+        id: string;
+        run: (input: unknown) => Promise<unknown>;
+    }): void;
+}
+/**
+ * The `name` of the `Error` an action's `run` throws to say the CALLER's input was malformed (a
+ * missing or wrong-typed field, a bad `owner/name`, ...) as opposed to something going wrong in the
+ * world (a GitHub failure, a store that isn't cloned): the host's action route
+ * (`POST /api/actions/:pluginId/:actionId`) answers such an error `400` with its message, and any
+ * other thrown error `500`.
+ *
+ * A NAME, deliberately not a class the host exports for plugins to import: a plugin server imports
+ * `@ac/contract` as `import type` only (`docs/plugins/authoring.md` §2 -- its compiled `dist/server.js`
+ * carries no runtime imports), and a class here would give every plugin a runtime dependency on it,
+ * while `instanceof` cannot see across a rollup-bundled server that inlines its own copy. Each plugin
+ * that validates input carries a small local class instead (the `AbortError` idiom), typed against
+ * this name so renaming it here fails the plugin's build rather than silently turning its 400s into
+ * 500s:
+ *
+ * ```ts
+ * import type { ActionInputErrorName } from "@rackbops/ac-plugin-contract"
+ *
+ * export class ActionInputError extends Error {
+ *   override name: ActionInputErrorName = "ActionInputError"
+ * }
+ * ```
+ *
+ * Types only: no runtime export, no `HOST_API_VERSION` bump.
+ */
+export type ActionInputErrorName = "ActionInputError";
+/**
+ * The in-process composition-slot binding (#84): a plugin registers its provider instance for a slot
+ * it `contributes.provides` in `activate()`; the host holds the one process-level binding and resolves
+ * it for the pipeline (`auth@1`) or another plugin (`notify@1`, #87) to call. Deliberately untyped by
+ * slot here (`impl: unknown`) -- the host casts to the slot's real interface (`AuthProvider`,
+ * `NotifyProvider`, `slots.ts`) when it resolves, the same way `RoutesService`/`ActionsService` don't
+ * know their callers' payload shapes either. Two providers for the same `slot@version` is a boot
+ * error (auth/notify are singletons) -- surfaced by the host-side registry `provide` throws from, not
+ * this interface, since this is the plugin's OWN scoped view (pre-bound to its id, so the error can
+ * name the real offending plugin without a pluginId parameter here). */
+export interface SlotRegistry {
+    /** Register this plugin's provider instance for `slot@version`. Throws if that slot already has a
+     *  provider (from this plugin or another) -- auth/notify are singletons, never a last-write-wins. */
+    provide(slot: string, version: number, impl: unknown): void;
+}
+/** A logger prefixed with the plugin id. */
+export interface LogService {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Read declared env keys only (the manifest's `env[]`). */
+export interface EnvService {
+    get(key: string): string | undefined;
+}
+/**
+ * Register HTTP handlers for the plugin's declared routes. The host mounts each under the plugin's
+ * own namespace `/api/x/<id>/…` (never bare); `handler` is a web-standard `Request` -> `Response`, so
+ * a plugin does not depend on the host's server. A plugin may only register a `(method, path)` it
+ * declared in its manifest `contributes.routes[]`. (Same-origin/CSRF protection of mutating routes is
+ * added across every mutating route by #85.)
+ */
+export interface RoutesService {
+    register(method: HttpMethod, path: string, handler: (request: Request) => Response | Promise<Response>): void;
+}
+/** The server-side services passed to `createPlugin(host)`. */
+export interface HostApi {
+    settings: SettingsService;
+    storage: StorageService;
+    jobs: JobsService;
+    events: EventsService;
+    github: GithubService;
+    agent: AgentService;
+    sidecar: SidecarService;
+    routes: RoutesService;
+    actions: ActionsService;
+    log: LogService;
+    env: EnvService;
+    /** #78: see `PluginJobsService`. Optional -- only `overview`'s needs-attention rollup uses it. */
+    plugins?: PluginJobsService;
+    /** #84: see `SlotRegistry`. */
+    slots: SlotRegistry;
+}
+/**
+ * The context the host passes to `Plugin.runJob` for one job run (#31). `jobId` selects which
+ * contributed job to run (one `runJob` dispatches all of the plugin's `contributes.jobs[]`); `signal`
+ * aborts when the run exceeds its `timeoutSec`, and a cooperative job should stop when it fires; `log`
+ * appends a line to THIS run's recorded log tail. Only lines written to `log` appear in the run
+ * record — `host.log` is operational logging and is not captured in the tail. `machine` is present
+ * for every run of a `runOn: "agent"` job (one run per paired machine, #51) and absent for a
+ * `runOn: "host"` job, which runs once with no machine.
+ */
+export interface JobRunContext {
+    jobId: string;
+    signal: AbortSignal;
+    log(line: string): void;
+    machine?: {
+        id: string;
+        name: string;
+    };
+}
+/** A plugin instance. `createPlugin(host)` is pure; I/O only in `activate()` (design §4 lifecycle). */
+export interface Plugin {
+    activate(): void | Promise<void>;
+    /**
+     * Run one of the plugin's contributed jobs, dispatched by `ctx.jobId` (#31's scheduler). Optional —
+     * a plugin that contributes no jobs omits it; the host records a job as failed if it is declared but
+     * no `runJob` is exported. A `runOn: "host"` job runs in-process once; a `runOn: "agent"` job runs
+     * in-process too, once per currently paired machine, with `ctx.machine` set (#51) — the agent itself
+     * runs no plugin code, so machine-side work goes through `host.agent.call(ctx.machine.id, …)` (#50).
+     */
+    runJob?(ctx: JobRunContext): void | Promise<void>;
+}
+/** A plugin's server entry: `dist/server.js` exports this as `createPlugin`. */
+export type CreatePlugin = (host: HostApi) => Plugin;
+/** Toast severity, matching notify. */
+export type ToastSeverity = "info" | "warning" | "error";
+/**
+ * The browser-side `@ac/host` a frontend bundle imports. v1 (implemented in #32) is `theme` tokens +
+ * `toast`; a `fetch` wrapper and `slots` grow additively when a consumer needs them (the issues panel,
+ * E5). The E3 chrome-integrated upgrade landed across #38 (toast portal), #41 (modal), and #142
+ * (quickcast). Methods are added additively — a breaking change bumps `HOST_API_VERSION`.
+ */
+export interface BrowserHostApi {
+    /** Show a toast. */
+    toast(message: string, opts?: {
+        severity?: ToastSeverity;
+    }): void;
+    /** Resolve a theme token (a `--rb-*` custom property) to its current value. */
+    theme: {
+        token(name: string): string;
+    };
+    /**
+     * The shell's header button slot (#38): put a button in the header; returns the unregister. Safe to
+     * call from a mounted panel/card (an effect) or at bundle import time — a registration made before the
+     * shell mounts is held and delivered when it does, and its unregister works in either state.
+     */
+    header: {
+        registerButton(button: HeaderButtonSpec): () => void;
+    };
+    /**
+     * Open the universal confirm modal for a registered action (#41). Fire-and-forget (returns nothing);
+     * safe to call before the shell mounts — held and opened once it does, or dropped if it never mounts,
+     * the same pending-buffer semantics as `header.registerButton`.
+     *
+     * `subscribe` (#460) is the completion signal `open` lacks: the listener runs once for every action
+     * the modal actually dispatched and got a result for -- success or failure -- whoever opened it (a
+     * plugin's `open`, the Ctrl+K palette), so a panel can refresh what an action just changed. A Cancel
+     * or Escape never fires it. Returns the unsubscribe. A listener that throws is logged and skipped;
+     * it never reaches the modal or another listener.
+     */
+    actions: {
+        open(ref: ActionOpenRef): void;
+        subscribe(listener: (event: ActionSettledEvent) => void): () => void;
+    };
+    /**
+     * Register a source of quickcast items for the shell's Ctrl+K palette (#40): the palette calls every
+     * registered source on open (and again on each filter pass) and lists the collected items after its
+     * own built-in panel/action items, in registration order. The plugin's `run` decides what happens
+     * (navigate, open its own UI, call `actions.open`); the palette closes and then calls `run`. Returns
+     * the unregister. Safe to call before the shell mounts — held and delivered when it does, the same
+     * pending-buffer semantics as `header.registerButton`.
+     */
+    quickcast: {
+        register(source: () => QuickcastItem[]): () => void;
+    };
+    /**
+     * Same-origin fetch to a host/plugin route (E5 #56, 56c). A relative `path` resolves against the
+     * console origin; an absolute `path` whose origin differs from the console's own is REJECTED (throws)
+     * rather than followed -- `credentials: "same-origin"` alone would not stop the request itself, or a
+     * write's `X-AC-CSRF` token, from reaching a third-party origin. Credentials are included
+     * (`same-origin`); a non-GET/HEAD/OPTIONS request carries the `X-AC-CSRF` token fetched once from
+     * `GET /api/config` (#85) and cached -- defense-in-depth alongside the Origin check #85 already
+     * enforces, not itself required yet. Panels read a provider's routes (e.g.
+     * `/api/x/provider-github/…`) through this rather than a bare `fetch`. Returns the raw `Response`;
+     * the caller parses it.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * `fetch`, wrapped in a per-path TTL cache (E7 #77): only `GET` may be cached (throws on any
+     * other method); a call within `ttlMs` (default 45 s) of the path's last fetch reuses that SAME
+     * underlying request rather than issuing a new one, and each caller gets its own `Response` via
+     * `.clone()` -- two independent reads of a cache hit never collide on an already-consumed body.
+     * A rejected fetch is dropped immediately, not cached for the rest of the window. A card reads
+     * through `cached`, never bare `fetch`, so Refresh (`invalidate`) and the heartbeat reach it.
+     */
+    cached(path: string, init?: RequestInit, opts?: {
+        ttlMs?: number;
+    }): Promise<Response>;
+    /** Bypass the cache: drop one path's entry, or every entry when `path` is omitted (Refresh). */
+    invalidate(path?: string): void;
+}
+/** One entry a plugin contributes to the quickcast palette (#40, #142). */
+export interface QuickcastItem {
+    label: string;
+    hint?: string;
+    run: () => void;
+}
+/** A button a plugin contributes to the shell header (#38). Re-registering an `id` replaces it. */
+export interface HeaderButtonSpec {
+    id: string;
+    label: string;
+    onClick: () => void;
+}
+/**
+ * Which registered action to open the universal modal for (#41), and what it operates on. `target`
+ * scopes the draft key (e.g. an issue number) when the action is opened against a specific object;
+ * omitted for a `scope: "global"` action, which falls back to the action's own `scope` as the key.
+ */
+export interface ActionOpenRef {
+    pluginId: string;
+    actionId: string;
+    target?: string;
+    /** Initial field values for this open (#71a). An explicit seed WINS over a stored draft for the same
+     *  scope key -- for the fields it NAMES (#478): every other field keeps the draft's value, else its
+     *  default, so text typed into the form survives a cancel and a seeded reopen. The merged values are
+     *  written as the draft at once, so a reload keeps exactly what the form shows. A field the seed names as
+     *  empty (`""`, `[]`, `0`, `false`) still wins -- so seed only what you know, and omit a key rather than
+     *  seed `""` for "unknown" -- and only an absent key (or `undefined`) leaves it to the draft. Absent
+     *  `input` -> the draft's values for the action's own fields, then the field defaults. A key not among the action's
+     *  declared `fields` is dropped, from the seed and from the draft, before it ever reaches the form or
+     *  the submitted input, so a stale/mistargeted seed can never post a stray field. A seed must name every
+     *  field whose meaning depends on another field it names (`originalLabels` with `labels`): the one it
+     *  leaves out keeps a possibly stale drafted value. */
+    input?: Record<string, unknown>;
+}
+/**
+ * What `actions.subscribe` delivers (#460): one action the universal modal dispatched and got a
+ * result for. `target` is the opened ref's own `target` (absent when the opener passed none -- the
+ * Ctrl+K palette carries none, and a `scope: "global"` action is usually opened without one) -- what it
+ * was opened FOR, not what the operator finally typed into the form. `error` is the failure message
+ * (the server's `error` text, or a client-side one such as `http 500`, a network error or a timeout).
+ * The event carries no input -- a listener can refetch what changed but never read what was sent.
+ */
+export interface ActionSettledEvent {
+    pluginId: string;
+    actionId: string;
+    target?: string;
+    ok: boolean;
+    error?: string;
+}
+//# sourceMappingURL=host-api.d.ts.map

package/dist/host-api.js

@@ -0,0 +1,10 @@
+/**
+ * `HostApi` is the service surface the host passes to `createPlugin(host)` on the server, and the
+ * `@ac/host` module the shell exposes to frontend bundles in the browser (design.md §3). This is
+ * the v1 shape; the server implementation landed in #28, with `sidecar` real as of #29's proxy,
+ * `jobs` as of #31's scheduler, `agent` as of E4, and `github` real as of #127's Octokit client; the
+ * browser side lands in #32. Methods are added additively — a breaking change bumps
+ * `HOST_API_VERSION`.
+ */
+export {};
+//# sourceMappingURL=host-api.js.map

package/dist/index-envelope.d.ts

@@ -0,0 +1,36 @@
+import type { EnvVar } from "./manifest.js";
+/**
+ * The plugin-index envelope (#35) — the `plugins.json` shape a host publishes so others can discover its
+ * plugins, shared with the discord-bot index (design §4): the same `schemaVersion`/`generatedAt` header
+ * and the per-plugin fields `name`, `package`, `version`, `hostApiVersion`, `env[]`, `releases[]`, plus a
+ * `host` discriminator so one repo could serve both hosts. `contributes` is deliberately NOT here — it is
+ * private to each host. These are pure types; they are not part of the manifest JSON Schema (`gen-schema`
+ * generates only from `AcPluginManifest`), so adding this file does not change `schema.json`.
+ */
+/** One published release of a plugin, derived from its CHANGELOG. */
+export interface Release {
+    version: string;
+    /** ISO date of the release, from the CHANGELOG section. */
+    date: string;
+    /** The CHANGELOG section body, if any. */
+    notes?: string;
+}
+/** One plugin's entry in an index. `name` is the shared identifier (AC2 sources it from the manifest `id`). */
+export interface PluginIndexEntry {
+    /** Which host this plugin targets, e.g. "artifact-console" — the discriminator on a shared index. */
+    host: string;
+    name: string;
+    /** The npm/package name (package.json `name`). */
+    package: string;
+    version: string;
+    hostApiVersion: number;
+    env: EnvVar[];
+    releases: Release[];
+}
+/** A `plugins.json` index. `generatedAt` is stamped by a publishing registry; a workspace drift-copy omits it. */
+export interface PluginIndex {
+    schemaVersion: number;
+    generatedAt?: string;
+    plugins: PluginIndexEntry[];
+}
+//# sourceMappingURL=index-envelope.d.ts.map

package/dist/index-envelope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index-envelope.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@ac/contract` — the plugin ABI: the `acPlugin` manifest + contribution points, the `HostApi`
+ * services, the four composition slots, and the version constants. The manifest's JSON Schema is
+ * generated from these types by `gen-schema.mjs` into `schema.json`.
+ */
+export type * from "./action-options.js";
+export type * from "./attention.js";
+export type * from "./host-api.js";
+export type * from "./index-envelope.js";
+export * from "./issue-filter.js";
+export type * from "./manifest.js";
+export * from "./ov-widgets.js";
+export type * from "./slots.js";
+export { HOST_API_VERSION, SLOTS } from "./version.js";
+export type * from "./views.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@ac/contract` — the plugin ABI: the `acPlugin` manifest + contribution points, the `HostApi`
+ * services, the four composition slots, and the version constants. The manifest's JSON Schema is
+ * generated from these types by `gen-schema.mjs` into `schema.json`.
+ */
+export * from "./issue-filter.js";
+export * from "./ov-widgets.js";
+export { HOST_API_VERSION, SLOTS } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/issue-filter.d.ts

@@ -0,0 +1,122 @@
+import type { IssueRecord } from "./slots.js";
+/**
+ * The shared filter model (E5 #56, 56c, plan of record decision 4): the eight-axis filter types + a
+ * pure `matchesIssue` predicate over the `IssueRecord` shape 56a shipped. Both issue panels — Board
+ * (#63) and Classic (#59) — apply this SAME predicate, so their counts agree by construction; neither
+ * panel depends on the other, and the predicate lives here (the shared/provider layer) rather than in
+ * either. `now` is always injected, never read from `Date.now()` internally, so a caller's tests (and
+ * this module's own) are deterministic.
+ */
+export type FilterOp = "is" | "is-not";
+/**
+ * A set-membership test: `is` matches when the record's value is in `values`; `is-not` when it is not.
+ * A value is a plain exact match (a label name, a login) UNLESS it is one of the tokens below (#464a):
+ * `@me`, `@unassigned`, `@bots`, `@any`, `@upto:<label>` -- which the predicate resolves against the record
+ * and a `MatchContext`. Any OTHER value, including one that merely starts with `@` (a label may be named
+ * `@needs-review`), is still the plain exact match it always was.
+ */
+export interface SetFilter {
+    op: FilterOp;
+    values: string[];
+}
+/** The viewer: an assignee/author login equal to `MatchContext.me`, compared ignoring case. */
+export declare const FILTER_ME = "@me";
+/** Nobody: on `assignee`, a record with no assignee; on `author`, a record with no author. */
+export declare const FILTER_UNASSIGNED = "@unassigned";
+/** A bot: an assignee/author whose `Person.isBot` is true -- GitHub's own flag, never a guess from the login. */
+export declare const FILTER_BOTS = "@bots";
+/** Any label of the axis's ladder (`priority`/`effort`/`type`). `is-not @any` is 1.x's "none". */
+export declare const FILTER_ANY = "@any";
+/**
+ * "At or before this rung of the ladder" (`priority`/`effort`): the record carries the label named
+ * `name` or any label the axis's ladder lists BEFORE it -- "High and above" on the priority ladder
+ * (critical first), "S and below" on the effort ladder (XS first): one rule, two wordings. `name` is the
+ * full label name, as the ladder carries it.
+ */
+export declare function filterUpTo(name: string): string;
+/** A filter value read as a token; `unknown` is an `@...` that is none of the tokens this version defines --
+ *  the predicate compares it as a plain value (so it matches nothing unless a label/login is spelled so). */
+export type FilterToken = {
+    kind: "me" | "unassigned" | "bots" | "any";
+} | {
+    kind: "upto";
+    name: string;
+} | {
+    kind: "unknown";
+    value: string;
+};
+/**
+ * A value as a token, or `undefined` for a plain value (one not starting with `@`). For the UIs' chip
+ * labels; the predicate reads values through it too, so what a chip says and what a filter does cannot
+ * disagree about what is a token. An `@...` that is not one of the five tokens comes back as `unknown`,
+ * which the predicate treats as a plain value.
+ */
+export declare function parseFilterToken(value: string): FilterToken | undefined;
+/**
+ * What a token needs from outside the record (#464a): the viewer's login for `@me`, and each ladder axis's
+ * label names in the standard's own order (critical first, XS first) for `@any` and `@upto:`. Every field
+ * is optional: a token that cannot be resolved without one it was not given matches nothing. Passed as
+ * `matchesIssue`'s optional fourth argument, so every three-argument caller behaves exactly as before.
+ */
+export interface MatchContext {
+    me?: string;
+    ladders?: {
+        priority?: string[];
+        effort?: string[];
+        type?: string[];
+    };
+}
+/** An age/activity bucket, measured from `now` against a record's `createdAt`/`updatedAt`. */
+export type AgeBucket = "1d" | "1w" | "1m" | "3m" | "older";
+export interface AgeFilter {
+    op: FilterOp;
+    buckets: AgeBucket[];
+}
+/**
+ * Every axis is optional; an absent axis imposes no constraint. `priority`/`effort`/`type`/`tags` are
+ * all "the record has a label whose name is in the set" -- the UI groups labels into these ladders
+ * (from `labels.json`, #58), but for a plain value the predicate treats all four identically: a plain
+ * label-name test. A token (#464a) adds `@any` and `@upto:<rung>` on the ladder axes, resolved against
+ * `MatchContext.ladders`; `tags` has no ladder, so a token there matches nothing.
+ */
+export interface IssueFilter {
+    priority?: SetFilter;
+    effort?: SetFilter;
+    type?: SetFilter;
+    tags?: SetFilter;
+    /** Over `assignees[].login`; a record with no assignees matches `is-not` of any set of plain logins, never
+     *  `is` -- `@unassigned` is the token that matches exactly that record, `@me`/`@bots` the viewer/bots. */
+    assignee?: SetFilter;
+    /** Over the single `author?.login`; `undefined` never matches `is` of a plain login, always matches
+     *  `is-not` (`@unassigned` matches a record with no author; `@me`/`@bots` as for `assignee`). */
+    author?: SetFilter;
+    /** Bucket of `now - createdAt`. */
+    age?: AgeFilter;
+    /** Bucket of `now - updatedAt`. */
+    activity?: AgeFilter;
+    /** Title substring (case-insensitive) OR an exact `#<number>` match (a leading `#` is stripped). */
+    search?: string;
+}
+/** Classic's list sort order (#59b). Lives here (not in the Classic plugin) so a `SavedView`'s
+ *  `sort` field and the panel's own sort state share ONE type instead of two independently-typed
+ *  string unions that could drift. */
+export type SortMode = "opened" | "priority" | "updated";
+/**
+ * A saved view (#60): a named filter+sort bundle a picker applies in one click, replacing the whole
+ * filter state (never merging into it, per 1.x's own documented decision -- a leftover axis would
+ * make a view mean something different depending on what preceded it). Config, not localStorage:
+ * `views.yaml` (the issues-classic plugin's own loader) ships the 1.x five as defaults and is the
+ * source of truth once an operator edits the file.
+ */
+export interface SavedView {
+    name: string;
+    filter: IssueFilter;
+    sort: SortMode;
+}
+/**
+ * Pure AND across every present axis. An empty `filter` (`{}`) matches every record. `ctx` (#464a) is what
+ * the filter's tokens resolve against (the viewer, the ladders); omit it and every plain value behaves
+ * exactly as it always did, while a token that needs `ctx` matches nothing.
+ */
+export declare function matchesIssue(record: IssueRecord, filter: IssueFilter, now: number, ctx?: MatchContext): boolean;
+//# sourceMappingURL=issue-filter.d.ts.map