@tablecraft-app/plugin-api 1.1.0 → 1.3.0

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Failures the host tells apart; anything else a plugin throws is reported as `statementFailed`. */
-export declare const PLUGIN_ERROR_CODES: readonly ["cancelled", "connectionFailed", "statementFailed", "introspectionFailed", "definitionNotFound", "explainUnsupported", "connectionLost", "sessionBusy"];
+export declare const PLUGIN_ERROR_CODES: readonly ["cancelled", "connectionFailed", "statementFailed", "introspectionFailed", "definitionNotFound", "explainUnsupported", "connectionLost", "sessionBusy", "conflict"];
 export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number];
 /**
  * Where the database located a failure, relative to the statement text the plugin received:
@@ -46,6 +46,15 @@ export declare class TlsSettingsError extends PluginError {
 }
 /** Structural for the same reason as `isPluginError`. */
 export declare function isTlsSettingsError(error: unknown): error is TlsSettingsError;
+/**
+ * A guarded `Keyspace.apply` found `target` changed since it was read (decision 115): `detail`
+ * says what differs, such as `field name is now "Bo"`. Nothing was written.
+ */
+export declare class ConflictError extends PluginError {
+    readonly target: string;
+    readonly detail: string;
+    constructor(target: string, detail: string, options?: ErrorOptions);
+}
 /**
  * `Introspector.definition` asked for a relation the database does not have, usually one dropped
  * or renamed since the catalog was read (decision 029). Coded `definitionNotFound`, so the host

package/dist/errors.js

@@ -18,6 +18,11 @@ export const PLUGIN_ERROR_CODES = [
      * reconnecting; never a message for the user.
      */
     "sessionBusy",
+    /**
+     * A guarded write found what it was to change already changed by someone else, and wrote
+     * nothing (decision 115); the host offers to reload or to overwrite.
+     */
+    "conflict",
 ];
 /** What a plugin throws when the host should react to the kind of failure, not just show it. */
 export class PluginError extends Error {
@@ -90,6 +95,19 @@ export class TlsSettingsError extends PluginError {
 export function isTlsSettingsError(error) {
     return isPluginError(error) && error.tlsSettings === true;
 }
+/**
+ * A guarded `Keyspace.apply` found `target` changed since it was read (decision 115): `detail`
+ * says what differs, such as `field name is now "Bo"`. Nothing was written.
+ */
+export class ConflictError extends PluginError {
+    target;
+    detail;
+    constructor(target, detail, options) {
+        super("conflict", `${target} changed since it was read: ${detail}. Reload it, or overwrite the change.`, options);
+        this.target = target;
+        this.detail = detail;
+    }
+}
 /**
  * `Introspector.definition` asked for a relation the database does not have, usually one dropped
  * or renamed since the catalog was read (decision 029). Coded `definitionNotFound`, so the host

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export { byName, type ColumnMeta, type ForeignKey, type Index, type Introspector, type Key, type Namespace, type NamespaceCatalog, type Relation, type RelationKind, ROUTINE_PARAMETER_MODES, type Routine, type RoutineParameter, type RoutineParameterMode, type Sequence, } from "./catalog.js";
 export { COMPLETION_KINDS, type CompletionCatalog, type CompletionItem, type CompletionKind, type CompletionRequest, type CompletionResult, type CompletionScope, type CompletionServer, type Declaration, type FunctionParameter, type FunctionSignature, type IncomingForeignKey, type ResolveRequest, type SignatureHelp, } from "./completion.js";
 export { INSPECTION_IDS, type InspectionId, type InspectionRequest, type Problem, PROBLEM_SEVERITIES, type ProblemSeverity, type QuickFix, type TextEdit, } from "./inspection.js";
-export { DefinitionNotFoundError, type ErrorPosition, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, type PluginErrorCode, type PluginErrorOptions, TlsSettingsError, } from "./errors.js";
+export { ConflictError, DefinitionNotFoundError, type ErrorPosition, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, type PluginErrorCode, type PluginErrorOptions, TlsSettingsError, } from "./errors.js";
 export { type ExplainedPlan, type Explainability, type ExplainOptions, type PlanNode, type PlanProperty, } from "./explain.js";
+export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type KeyChange, type KeyContents, type KeyDatabase, type KeyDetails, type KeyExpiry, type KeyInfo, type KeyName, type KeyReadRequest, type KeyScan, type KeyScanRequest, type KeySource, type Keyspace, type KeyType, } from "./keyspace.js";
 export { OBJECT_KINDS, type CatalogObject, type CheckDesign, type ColumnDesign, type DdlContext, type DdlScript, type ForeignKeyDesign, type IndexDesign, type ObjectChange, type ObjectChangeKind, type ObjectEditor, type ObjectFeatures, type ObjectKind, type TableDesign, } from "./objects.js";
 export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, type ConnectionField, type ConnectionFieldGroup, type ConnectionFieldKind, type ConnectionUrl, type ConnectionUrlForm, type ConnectionUrlPart, type NetworkSpec, type PluginManifest, type TlsFieldRole, type TlsSpec, } from "./manifest.js";
 export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, type ConnectionForm, type ConnectionUrlSpec, type ConnectionValue, type ParsedConnectionUrl, } from "./url.js";
-export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
+export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
 export { SERVER_SESSION_STATES, type ServerSession, type ServerSessionState, type SessionListing, type SessionMonitor, type SessionTarget, } from "./sessions.js";
 export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, type TlsVerification, } from "./tls.js";
 export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, type WireValueOptions, type BigIntValue, type BytesValue, type DateValue, type JsonValue, type TypeClass, type WireValue, } from "./values.js";

package/dist/index.js

@@ -1,12 +1,13 @@
 export { byName, ROUTINE_PARAMETER_MODES, } from "./catalog.js";
 export { COMPLETION_KINDS, } from "./completion.js";
 export { INSPECTION_IDS, PROBLEM_SEVERITIES, } from "./inspection.js";
-export { DefinitionNotFoundError, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, TlsSettingsError, } from "./errors.js";
+export { ConflictError, DefinitionNotFoundError, errorPositionOf, isPluginError, isTlsSettingsError, offsetOfPosition, PLUGIN_ERROR_CODES, PluginError, TlsSettingsError, } from "./errors.js";
 export {} from "./explain.js";
+export { KEY_TYPES, } from "./keyspace.js";
 export { OBJECT_KINDS, } from "./objects.js";
 export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, } from "./manifest.js";
 export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, } from "./url.js";
-export { CAPABILITIES, FORMAT_STYLES, GENERATED_STATEMENTS, IMPORT_KINDS, KEYWORD_CASES, switchableTo, PARAMETER_STYLES, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, STATEMENT_KINDS, TRANSACTION_MODES, } from "./plugin.js";
+export { CAPABILITIES, FORMAT_STYLES, GENERATED_STATEMENTS, IMPORT_KINDS, KEYWORD_CASES, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, switchableTo, PARAMETER_STYLES, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, STATEMENT_KINDS, TRANSACTION_MODES, } from "./plugin.js";
 export { SERVER_SESSION_STATES, } from "./sessions.js";
 export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, } from "./tls.js";
 export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, } from "./values.js";

package/dist/keyspace.d.ts

@@ -0,0 +1,192 @@
+import type { ExecuteResult } from "./plugin.js";
+import type { WireValue } from "./values.js";
+/** The key types the key tree tells apart (decision 113); a module type such as RedisJSON is `other`. */
+export declare const KEY_TYPES: readonly ["string", "hash", "list", "set", "zset", "stream", "json", "other"];
+export type KeyType = (typeof KEY_TYPES)[number];
+/**
+ * Bytes that are usually text, such as a key name, a hash field or a value (decision 113). `text`
+ * is the UTF-8 reading with each invalid byte written `\xNN`, as `redis-cli` prints it; `hex` is
+ * every byte in lower-case hex when the bytes are not valid UTF-8, and null when they are. Sent
+ * back to the plugin, `hex` wins when present.
+ */
+export interface KeyBytes {
+    readonly text: string;
+    readonly hex: string | null;
+}
+/** A key's name: bytes, since a key may be any binary string. */
+export type KeyName = KeyBytes;
+/**
+ * The one key a command's reply was read from (decision 119), so the host can open the key or
+ * edit the reply as the key. `whole` is true when the reply holds the entire key, such as
+ * `HGETALL` or `LRANGE k 0 -1`; its columns are then the ones `Keyspace.read` gives that type,
+ * without positions a key tab adds (a zset's `#`), and a string's is one `value` column.
+ */
+export interface KeySource {
+    readonly database: number;
+    readonly key: KeyName;
+    readonly type: KeyType;
+    readonly whole: boolean;
+}
+/** One logical database of the keyspace: Redis' `db0`–`db15`, or the one database of a cluster. */
+export interface KeyDatabase {
+    readonly index: number;
+    readonly keys: number;
+    /** Keys with a time to live. */
+    readonly expires: number;
+    /** The database the connection is configured with. */
+    readonly current: boolean;
+}
+export interface KeyScanRequest {
+    readonly database: number;
+    /** Null starts a pass; otherwise what the last `KeyScan.cursor` said, opaque to the host. */
+    readonly cursor: string | null;
+    /** A glob, as `SCAN … MATCH` takes it; `*` for every key. */
+    readonly match: string;
+    readonly type: KeyType | null;
+    /**
+     * The batch the server is asked to look at per round trip, not a promise of how many keys come
+     * back; absent, the datasource's own setting.
+     */
+    readonly count?: number;
+}
+export interface KeyScan {
+    readonly keys: readonly KeyName[];
+    /** Null when the pass reached the end. */
+    readonly cursor: string | null;
+    /** Keys the server looked at, matching or not, so the host can say how far the pass got. */
+    readonly scanned: number;
+}
+export interface KeyInfo {
+    readonly key: KeyName;
+    /** Null when the key does not exist (any more). */
+    readonly type: KeyType | null;
+    /** The server's name for the type, such as `ReJSON-RL` for `other` and `json`. */
+    readonly typeName: string | null;
+    /** Milliseconds left to live; null without an expiry. */
+    readonly ttlMs: number | null;
+}
+/** What the key tab's header shows; each field null when the server or its ACL would not say. */
+export interface KeyDetails extends KeyInfo {
+    /** Fields, elements, members, entries or bytes, by type. */
+    readonly length: number | null;
+    readonly memoryBytes: number | null;
+    readonly encoding: string | null;
+    readonly idleSeconds: number | null;
+}
+/** Which part of a key `Keyspace.read` returns (decision 113). */
+export interface KeyReadRequest {
+    /** A glob over hash fields and set or sorted-set members. */
+    readonly match?: string;
+    /** The first stream id, `-` by default; the last is `to`, `+` by default. */
+    readonly from?: string;
+    readonly to?: string;
+    /** The first list or sorted-set index read. */
+    readonly offset?: number;
+    /** At most this many elements. */
+    readonly window: number;
+}
+/**
+ * A key's contents: the elements as a result the host opens in its grid, or, for a string or a
+ * type it does not read element by element, one value.
+ */
+export interface KeyContents {
+    readonly details: KeyDetails;
+    /** Rows of the elements: hash `field`, `value`; list `#`, `value`; and so on. Null for a string. */
+    readonly result: ExecuteResult | null;
+    /** The value of a string or of a JSON document, every byte up to the plugin's limit. */
+    readonly value: WireValue | null;
+    /** Why the contents cannot be edited, such as a value read only in part; null when they can. */
+    readonly readOnly: string | null;
+}
+/**
+ * One pending change to one key. `original` is what the element held when it was read, which a
+ * guarded apply checks first (decision 115); null for an element that did not exist.
+ */
+export type KeyChange = {
+    readonly kind: "setString";
+    readonly value: KeyBytes;
+    readonly original: KeyBytes | null;
+} | {
+    readonly kind: "setField";
+    readonly field: KeyBytes;
+    readonly value: KeyBytes;
+    readonly original: KeyBytes | null;
+} | {
+    readonly kind: "deleteField";
+    readonly field: KeyBytes;
+    readonly original: KeyBytes;
+} | {
+    readonly kind: "setIndex";
+    readonly index: number;
+    readonly value: KeyBytes;
+    readonly original: KeyBytes;
+} | {
+    readonly kind: "deleteIndex";
+    readonly index: number;
+    readonly original: KeyBytes;
+} | {
+    readonly kind: "push";
+    readonly value: KeyBytes;
+} | {
+    readonly kind: "addMember";
+    readonly member: KeyBytes;
+} | {
+    readonly kind: "deleteMember";
+    readonly member: KeyBytes;
+} | {
+    readonly kind: "setScore";
+    readonly member: KeyBytes;
+    readonly score: number;
+    readonly original: number | null;
+} | {
+    readonly kind: "addEntry";
+    readonly fields: readonly (readonly [KeyBytes, KeyBytes])[];
+} | {
+    readonly kind: "deleteEntry";
+    readonly id: string;
+};
+export interface KeyApplyOptions {
+    /** The key's type as read, or the type of the key the changes create. */
+    readonly type: KeyType;
+    /** Check every change's `original` first and refuse with `conflict` when one differs. */
+    readonly guard: boolean;
+    /** Milliseconds to live to set with the changes, for a new key; absent leaves the expiry alone. */
+    readonly ttlMs?: number;
+}
+export interface KeyApplied {
+    /** The commands that ran, as `preview` lists them. */
+    readonly commands: readonly string[];
+}
+/** A new expiry: milliseconds from now, an instant, or none at all. */
+export type KeyExpiry = {
+    readonly inMs: number;
+} | {
+    readonly at: string;
+} | null;
+/**
+ * The keys of a key-value store, read and changed by the plugin (decision 113). Present on a
+ * session exactly when the plugin declares `keyValue`. Calls queue on the session they hang off.
+ */
+export interface Keyspace {
+    /** What separates the levels of a key name, such as `:`, for the tree's folders. */
+    readonly delimiter: string;
+    databases(): Promise<readonly KeyDatabase[]>;
+    /** One batch of a pass over the keys; nothing ever runs `KEYS`. */
+    scan(request: KeyScanRequest): Promise<KeyScan>;
+    /** Type and expiry of each key, in order. */
+    describe(database: number, keys: readonly KeyName[]): Promise<readonly KeyInfo[]>;
+    /** A key that does not exist reads with a null `details.type` and no contents. */
+    read(database: number, key: KeyName, request: KeyReadRequest): Promise<KeyContents>;
+    /** The commands `apply` would run for `changes`, numbered by the host. Pure. */
+    preview(key: KeyName, changes: readonly KeyChange[], options: KeyApplyOptions): readonly string[];
+    /**
+     * Runs `changes` as one `MULTI`. Guarded, it first checks every `original` and rejects with
+     * `conflict`, writing nothing, when one differs.
+     */
+    apply(database: number, key: KeyName, changes: readonly KeyChange[], options: KeyApplyOptions): Promise<KeyApplied>;
+    /** Rejects with `statementFailed` when `to` exists and `overwrite` is false, or the key is gone. */
+    rename(database: number, key: KeyName, to: KeyName, overwrite: boolean): Promise<void>;
+    expire(database: number, key: KeyName, expiry: KeyExpiry): Promise<void>;
+    /** Removes the keys that exist and says how many did. */
+    remove(database: number, keys: readonly KeyName[]): Promise<number>;
+}

package/dist/keyspace.js

@@ -0,0 +1,2 @@
+/** The key types the key tree tells apart (decision 113); a module type such as RedisJSON is `other`. */
+export const KEY_TYPES = ["string", "hash", "list", "set", "zset", "stream", "json", "other"];

package/dist/manifest.d.ts

@@ -36,6 +36,10 @@ export declare const connectionFieldSchema: z.ZodObject<{
         advanced: "advanced";
     }>>;
     secret: z.ZodOptional<z.ZodBoolean>;
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        equals: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ConnectionField = z.infer<typeof connectionFieldSchema>;
 /** `server`: `scheme://user:password@host:port/database?params`; `file`: a path, bare or as a URL. */
@@ -69,6 +73,7 @@ export declare const connectionUrlSchema: z.ZodObject<{
         key: z.ZodString;
         values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>>;
+    sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
 }, z.core.$strict>;
 export type ConnectionUrl = z.infer<typeof connectionUrlSchema>;
 /**
@@ -121,6 +126,10 @@ export declare const pluginManifestSchema: z.ZodObject<{
         serverMessages: "serverMessages";
         sessions: "sessions";
         routineCall: "routineCall";
+        commands: "commands";
+        keyValue: "keyValue";
+        nodes: "nodes";
+        serverInfo: "serverInfo";
     }>>;
     highlight: z.ZodString;
     connection: z.ZodObject<{
@@ -147,6 +156,10 @@ export declare const pluginManifestSchema: z.ZodObject<{
                 advanced: "advanced";
             }>>;
             secret: z.ZodOptional<z.ZodBoolean>;
+            visibleWhen: z.ZodOptional<z.ZodObject<{
+                key: z.ZodString;
+                equals: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         url: z.ZodOptional<z.ZodObject<{
             schemes: z.ZodArray<z.ZodString>;
@@ -167,6 +180,7 @@ export declare const pluginManifestSchema: z.ZodObject<{
                 key: z.ZodString;
                 values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$strict>>>;
+            sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
         }, z.core.$strict>>;
         network: z.ZodOptional<z.ZodObject<{
             host: z.ZodString;

package/dist/manifest.js

@@ -30,6 +30,13 @@ export const connectionFieldSchema = z.strictObject({
         .optional(),
     group: z.enum(CONNECTION_FIELD_GROUPS).optional(),
     secret: z.boolean().optional(),
+    /**
+     * Draw the field only while the `select` or `checkbox` named by `key` holds `equals` (plan 058);
+     * a hidden field is neither checked nor required.
+     */
+    visibleWhen: z
+        .strictObject({ key: z.string().regex(FIELD_KEY), equals: z.union([z.string(), z.boolean()]) })
+        .optional(),
 });
 /** `server`: `scheme://user:password@host:port/database?params`; `file`: a path, bare or as a URL. */
 export const CONNECTION_URL_FORMS = ["server", "file"];
@@ -54,6 +61,13 @@ export const connectionUrlSchema = z.strictObject({
         values: z.record(z.string(), z.string()).optional(),
     }))
         .optional(),
+    /**
+     * Field values a scheme implies, keyed by scheme, such as `rediss` setting the TLS mode (plan
+     * 058). A pasted URL fills them; a written URL takes the first scheme whose values the config holds.
+     */
+    sets: z
+        .record(z.string().regex(URL_SCHEME), z.record(z.string().regex(FIELD_KEY), z.union([z.string(), z.number(), z.boolean()])))
+        .optional(),
 });
 /**
  * Which fields hold the server's address (decision 070), so the host can open an SSH tunnel and
@@ -117,6 +131,30 @@ function tlsFieldsDeclared(connection) {
         return field !== undefined && tlsFieldFits(role, field, tls);
     });
 }
+/** Every `visibleWhen` names another field of the form, a `select` or a `checkbox`. */
+function visibilityFieldsDeclared(connection) {
+    return connection.fields.every((field) => {
+        const condition = field.visibleWhen;
+        if (condition === undefined)
+            return true;
+        const source = connection.fields.find((candidate) => candidate.key === condition.key);
+        return (source !== undefined &&
+            source !== field &&
+            (source.kind === "select" || source.kind === "checkbox") &&
+            typeof condition.equals === (source.kind === "checkbox" ? "boolean" : "string"));
+    });
+}
+/** Every scheme `url.sets` keys is one of `url.schemes`, and every value it sets is a declared field's. */
+function urlSetsDeclared(connection) {
+    const url = connection.url;
+    if (url?.sets === undefined)
+        return true;
+    return Object.entries(url.sets).every(([scheme, values]) => url.schemes.includes(scheme) &&
+        Object.keys(values).every((key) => connection.fields.some((field) => field.key === key)));
+}
+function includesAny(capabilities, ...wanted) {
+    return wanted.some((capability) => capabilities.includes(capability));
+}
 export const pluginManifestSchema = z
     .strictObject({
     id: z.string().regex(PLUGIN_ID, { message: "expected lower-case letters, digits and dashes" }),
@@ -144,8 +182,28 @@ export const pluginManifestSchema = z
         .refine(tlsFieldsDeclared, {
         message: "tls names a field the form does not declare or one of the wrong kind: mode a select offering every verify mode, files of kind file, the passphrase a secret password",
         path: ["tls"],
+    })
+        .refine(visibilityFieldsDeclared, {
+        message: "visibleWhen names a field the form does not declare, the field itself, or one that is not a select or checkbox, or compares it with a value of the wrong type",
+        path: ["fields"],
+    })
+        .refine(urlSetsDeclared, {
+        message: "url.sets names a scheme the url does not list, or a field the form does not declare",
+        path: ["url"],
     }),
 })
+    // A console speaks one language: SQL statements or a store's commands (decision 112).
+    .refine((manifest) => !(manifest.capabilities.includes("commands") && manifest.capabilities.includes("sql")), {
+    message: "the commands and sql capabilities exclude each other",
+    path: ["capabilities"],
+})
+    // The key tree's edits and actions are previewed and confirmed as commands (decision 113).
+    .refine((manifest) => !manifest.capabilities.includes("keyValue") || manifest.capabilities.includes("commands"), {
+    message: "the keyValue capability requires commands",
+    path: ["capabilities"],
+})
+    .refine((manifest) => !includesAny(manifest.capabilities, "nodes", "serverInfo") ||
+    includesAny(manifest.capabilities, "sql", "commands"), { message: "the nodes and serverInfo capabilities require sql or commands", path: ["capabilities"] })
     // A definition is read through the introspector, which only `schemaTree` promises (decision 029).
     .refine((manifest) => !manifest.capabilities.includes("ddl") || manifest.capabilities.includes("schemaTree"), {
     message: "the ddl capability requires schemaTree",
@@ -167,10 +225,14 @@ export const pluginManifestSchema = z
     // Object DDL is planned against described tables and reads its names from the introspector (decision 052).
     .refine((manifest) => !manifest.capabilities.includes("objects") ||
     (manifest.capabilities.includes("sql") && manifest.capabilities.includes("schemaTree")), { message: "the objects capability requires sql and schemaTree", path: ["capabilities"] })
-    // A listed session's query opens in a console, and the engine lists sessions on its introspection
-    // session, which only a schemaTree plugin opens (decision 088).
+    // A listed session's query opens in a console, and the engine lists sessions on its catalog or
+    // key-tree session (decision 088, plan 058).
     .refine((manifest) => !manifest.capabilities.includes("sessions") ||
-    (manifest.capabilities.includes("sql") && manifest.capabilities.includes("schemaTree")), { message: "the sessions capability requires sql and schemaTree", path: ["capabilities"] })
+    (includesAny(manifest.capabilities, "sql", "commands") &&
+        includesAny(manifest.capabilities, "schemaTree", "keyValue")), {
+    message: "the sessions capability requires sql or commands, and schemaTree or keyValue",
+    path: ["capabilities"],
+})
     // A call runs in a console and is built from the routine the introspector describes (decision 090).
     .refine((manifest) => !manifest.capabilities.includes("routineCall") ||
     (manifest.capabilities.includes("sql") && manifest.capabilities.includes("schemaTree")), { message: "the routineCall capability requires sql and schemaTree", path: ["capabilities"] });

package/dist/plugin.d.ts

@@ -3,6 +3,7 @@ import type { Introspector, Namespace, Relation, Routine } from "./catalog.js";
 import type { CompletionCatalog, CompletionRequest, CompletionResult, Declaration, ResolveRequest, SignatureHelp } from "./completion.js";
 import type { ExplainedPlan, Explainability, ExplainOptions } from "./explain.js";
 import type { InspectionRequest, Problem } from "./inspection.js";
+import type { KeySource, Keyspace } from "./keyspace.js";
 import type { ObjectEditor } from "./objects.js";
 import type { SessionMonitor } from "./sessions.js";
 import type { TypeClass, WireValue } from "./values.js";
@@ -10,7 +11,7 @@ import type { TypeClass, WireValue } from "./values.js";
  * What a plugin can do. The UI branches on these, never on a plugin id (decision 007), and a
  * capability without contract-suite coverage cannot be declared (decision 013).
  */
-export declare const CAPABILITIES: readonly ["sql", "cancel", "schemaTree", "transactions", "ddl", "explain", "explainAnalyze", "currentNamespace", "keepAlive", "bulkInsert", "objects", "serverMessages", "sessions", "routineCall"];
+export declare const CAPABILITIES: readonly ["sql", "cancel", "schemaTree", "transactions", "ddl", "explain", "explainAnalyze", "currentNamespace", "keepAlive", "bulkInsert", "objects", "serverMessages", "sessions", "routineCall", "commands", "keyValue", "nodes", "serverInfo"];
 export type Capability = (typeof CAPABILITIES)[number];
 /** Statements `SqlLanguage.generate` writes from a catalog relation (plan 010). */
 export declare const GENERATED_STATEMENTS: readonly ["drop", "select", "insert", "update"];
@@ -55,6 +56,29 @@ export interface ExecuteResult {
      * the plugin declares `serverMessages`.
      */
     readonly messages?: readonly ServerMessage[];
+    /**
+     * A command's one-value answer, such as a status, a number or a string (decision 112): the
+     * console shows it in Output and opens no result unless it is `read`. Only a `commands` plugin sets it, and then
+     * `columns` and `rows` are empty.
+     */
+    readonly reply?: CommandReply;
+    /**
+     * The one key the command read, when it read exactly one (decision 119); absent for writes,
+     * keyless and multi-key commands. Only a `keyValue` plugin sets it.
+     */
+    readonly source?: KeySource;
+}
+/** A scalar reply to a command (decision 112). */
+export interface CommandReply {
+    readonly value: WireValue;
+    /** The reply as the server's own client prints it: `"Ann"`, `(integer) 5`, `(nil)`, `OK`. */
+    readonly text: string;
+    /**
+     * The reply is a value read, such as a bulk string from `GET` or `HGET` or the nil of a missing
+     * one (decision 119): the console opens it as a one-row `value` result besides Output. Absent
+     * for statuses, numbers and errors, which stay in Output.
+     */
+    readonly read?: boolean;
 }
 /** How serious a `ServerMessage` is, from the server's own word for it. */
 export declare const SERVER_MESSAGE_LEVELS: readonly ["error", "warning", "notice", "info"];
@@ -92,6 +116,56 @@ export interface ExecuteOptions {
      * preview. For an export, which writes values whole (decision 040); a grid never asks.
      */
     readonly fullBytes?: boolean;
+    /**
+     * Where a command runs, for a plugin that declares `nodes` (decision 114): `NODE_AUTO` (absent
+     * means the same) lets the plugin route it, `NODE_ALL_PRIMARIES` runs it on every primary and
+     * leads each row with a `node` column, and anything else is a `ServerNode.id`.
+     */
+    readonly node?: string;
+}
+/** `ExecuteOptions.node`: the plugin routes the command by its keys (decision 114). */
+export declare const NODE_AUTO = "auto";
+/** `ExecuteOptions.node`: the command runs once on every primary (decision 114). */
+export declare const NODE_ALL_PRIMARIES = "allPrimaries";
+export declare const NODE_ROLES: readonly ["primary", "replica"];
+export type NodeRole = (typeof NODE_ROLES)[number];
+/** One server of the datasource (decision 114); a standalone server is one primary. */
+export interface ServerNode {
+    /** Stable while the cluster is: Redis' node id, or the address of a standalone server. */
+    readonly id: string;
+    /** `host:port`, as the client reaches it. */
+    readonly address: string;
+    readonly role: NodeRole;
+    /** Inclusive hash-slot ranges a primary serves; empty for a replica and a standalone server. */
+    readonly slots: readonly (readonly [number, number])[];
+    /** The primary a replica follows; null for a primary. */
+    readonly primaryId: string | null;
+    /** The server's word for its health, such as `connected` or `fail`. */
+    readonly state: string;
+}
+/** A titled group of a server's figures, such as Redis' `# Memory` section of `INFO` (decision 114). */
+export interface ServerInfoSection {
+    readonly title: string;
+    readonly entries: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+}
+/** One slow-log entry: when, for how long, what ran, and from where. */
+export interface SlowCommand {
+    readonly id: number;
+    /** ISO-8601. */
+    readonly at: string;
+    readonly durationMicros: number;
+    readonly command: string;
+    readonly client: string | null;
+    readonly node: string | null;
+}
+/** What `Session.serverInfo` reads about one node. */
+export interface ServerInfo {
+    /** The node, or null for a standalone server. */
+    readonly node: string | null;
+    readonly sections: readonly ServerInfoSection[];
 }
 /** Kinds a file importer infers from a column's text, narrowest first within each family (plan 021). */
 export declare const IMPORT_KINDS: readonly ["boolean", "integer", "bigint", "decimal", "double", "date", "timestamp", "text"];
@@ -174,6 +248,20 @@ export interface Session {
      * not say, and the host then matches by id alone.
      */
     readonly serverInstance?: string;
+    /** Present exactly when the plugin declares `keyValue` (decision 113). */
+    readonly keyspace?: Keyspace;
+    /**
+     * Present exactly when the plugin declares `nodes` (decision 114): every server of the
+     * datasource, primaries first; one entry for a single server.
+     */
+    nodes?(): Promise<readonly ServerNode[]>;
+    /**
+     * Present exactly when the plugin declares `serverInfo`: what `node` (a `ServerNode.id`, or null
+     * for the one server or a primary of the plugin's choice) reports about itself.
+     */
+    serverInfo?(node: string | null): Promise<ServerInfo>;
+    /** Present exactly when the plugin declares `serverInfo`: the newest `limit` slow commands, of every primary for a null `node`. */
+    slowLog?(node: string | null, limit: number): Promise<readonly SlowCommand[]>;
     /**
      * Settles in bounded time even when the network is gone: a graceful goodbye that does not
      * answer within a few seconds gives way to dropping the socket (decision 040).
@@ -254,6 +342,13 @@ export interface StatementClass {
      * `SET search_path` (plan 022); the host then asks `Session.currentNamespace` again.
      */
     readonly setsNamespace?: boolean;
+    /**
+     * Why the statement may be slow or heavy for the server, such as `KEYS walks every key`; the
+     * editor marks it and never blocks the run (decision 112). Null or absent when it is not.
+     */
+    readonly costly?: string | null;
+    /** With `destructive`: confirming it asks for the datasource's name, not just OK (decision 112). */
+    readonly confirmByName?: boolean;
 }
 export declare const KEYWORD_CASES: readonly ["upper", "lower", "preserve"];
 export type KeywordCase = (typeof KEYWORD_CASES)[number];
@@ -447,12 +542,33 @@ export interface Transactions {
     /** Whether a transaction is open after the last statement, commit or rollback. */
     readonly open: boolean;
 }
+/**
+ * The console language of a datasource that speaks commands, not SQL (decision 112): one command
+ * per line, as the server's own client reads them.
+ */
+export interface CommandLanguage {
+    /** Every command in `text`, in order; comments and blank lines belong to none. */
+    split(text: string): readonly StatementSpan[];
+    classify(command: string): StatementClass;
+    /**
+     * What fits at the caret. `session` is a connection the host keeps for such questions, null
+     * when it cannot open one; the plugin then completes from what it knows offline. Never rejects
+     * for text it cannot read.
+     */
+    complete(request: CompletionRequest, session: Session | null): Promise<CompletionResult>;
+    /** The command the caret is in and the argument it is at, for the parameter hint (decision 098). */
+    signatureAt?(request: CompletionRequest, session: Session | null): Promise<SignatureHelp | null>;
+    /** Problems in `request.text` found without running it, such as a costly command, with quick fixes. */
+    inspect?(request: InspectionRequest): Promise<readonly Problem[]>;
+}
 /** The default export of a plugin's entry module (decision 005). */
 export interface DatasourcePlugin {
     readonly id: string;
     readonly capabilities: readonly Capability[];
     /** Present exactly when the plugin declares `sql`. */
     readonly language?: SqlLanguage;
+    /** Present exactly when the plugin declares `commands` (decision 112). */
+    readonly commandLanguage?: CommandLanguage;
     /** Validates the configuration `connect` receives; the host parses before it calls. */
     readonly connectionSchema: z.ZodType;
     /** Rejects with a `PluginError` coded `connectionFailed` when the database cannot be reached. */

package/dist/plugin.js

@@ -17,6 +17,10 @@ export const CAPABILITIES = [
     "serverMessages",
     "sessions",
     "routineCall",
+    "commands",
+    "keyValue",
+    "nodes",
+    "serverInfo",
 ];
 /** Statements `SqlLanguage.generate` writes from a catalog relation (plan 010). */
 export const GENERATED_STATEMENTS = ["drop", "select", "insert", "update"];
@@ -32,6 +36,11 @@ export function omittedMessages(count) {
         text: `${String(count)} more server ${count === 1 ? "message is" : "messages are"} not shown.`,
     };
 }
+/** `ExecuteOptions.node`: the plugin routes the command by its keys (decision 114). */
+export const NODE_AUTO = "auto";
+/** `ExecuteOptions.node`: the command runs once on every primary (decision 114). */
+export const NODE_ALL_PRIMARIES = "allPrimaries";
+export const NODE_ROLES = ["primary", "replica"];
 /** Kinds a file importer infers from a column's text, narrowest first within each family (plan 021). */
 export const IMPORT_KINDS = ["boolean", "integer", "bigint", "decimal", "double", "date", "timestamp", "text"];
 export const STATEMENT_KINDS = ["read", "write", "ddl", "transaction", "other"];