@tablecraft-app/plugin-api 0.0.0-stage → 1.1.0

package/dist/manifest.d.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+/** The file that marks a directory as a plugin (decision 005). */
+export declare const MANIFEST_FILE = "table-craft-plugin.json";
+/**
+ * What the loader reads before executing any plugin code, so an unavailable plugin can still be
+ * named in the UI.
+ */
+export declare const CONNECTION_FIELD_KINDS: readonly ["text", "number", "password", "file", "select", "checkbox"];
+export type ConnectionFieldKind = (typeof CONNECTION_FIELD_KINDS)[number];
+export declare const CONNECTION_FIELD_GROUPS: readonly ["general", "advanced"];
+export type ConnectionFieldGroup = (typeof CONNECTION_FIELD_GROUPS)[number];
+/**
+ * One control of the connection form (decision 019). `key` names the config property it fills;
+ * `secret` sends the value to the secret store instead of `datasources.json` (decision 020).
+ */
+export declare const connectionFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    kind: z.ZodEnum<{
+        number: "number";
+        text: "text";
+        select: "select";
+        password: "password";
+        file: "file";
+        checkbox: "checkbox";
+    }>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>>;
+    group: z.ZodOptional<z.ZodEnum<{
+        general: "general";
+        advanced: "advanced";
+    }>>;
+    secret: z.ZodOptional<z.ZodBoolean>;
+}, 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. */
+export declare const CONNECTION_URL_FORMS: readonly ["server", "file"];
+export type ConnectionUrlForm = (typeof CONNECTION_URL_FORMS)[number];
+/** The pieces of a connection URL a field can take; `path` belongs to the `file` form. */
+export declare const CONNECTION_URL_PARTS: readonly ["host", "port", "database", "user", "password", "path"];
+export type ConnectionUrlPart = (typeof CONNECTION_URL_PARTS)[number];
+/**
+ * How a connection URL maps onto the form's fields (decision 055), so the host parses and writes
+ * one without running plugin code. `parts` names the field each piece of the URL fills; a query
+ * parameter fills `key`, its value translated through `values` (compared case-insensitively) when
+ * given, so a value outside them is reported as ignored.
+ */
+export declare const connectionUrlSchema: z.ZodObject<{
+    schemes: z.ZodArray<z.ZodString>;
+    form: z.ZodEnum<{
+        file: "file";
+        server: "server";
+    }>;
+    parts: z.ZodRecord<z.ZodEnum<{
+        database: "database";
+        path: "path";
+        password: "password";
+        host: "host";
+        port: "port";
+        user: "user";
+    }> & z.core.$partial, z.ZodString>;
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        key: z.ZodString;
+        values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ConnectionUrl = z.infer<typeof connectionUrlSchema>;
+/**
+ * Which fields hold the server's address (decision 070), so the host can open an SSH tunnel and
+ * hand the plugin `127.0.0.1` and the forwarded port instead. `connectTimeout`, in seconds, bounds
+ * the SSH hop too. Absent: the data source is not reached over the network and offers no tunnel.
+ */
+export declare const networkSpecSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodString;
+    connectTimeout: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type NetworkSpec = z.infer<typeof networkSpecSchema>;
+/**
+ * Which fields configure TLS (decision 072), so the dialog groups them under SSL, hints when a CA
+ * file goes unchecked, and main asks for the key passphrase only when the key file is encrypted.
+ * `mode` is the `select` of SSL modes; `verifyModes` are its values that check the server
+ * certificate. Absent: the plugin speaks no TLS the host knows about.
+ */
+export declare const tlsSpecSchema: z.ZodObject<{
+    mode: z.ZodString;
+    verifyModes: z.ZodArray<z.ZodString>;
+    caFile: z.ZodOptional<z.ZodString>;
+    certFile: z.ZodOptional<z.ZodString>;
+    keyFile: z.ZodOptional<z.ZodString>;
+    keyPassphrase: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type TlsSpec = z.infer<typeof tlsSpecSchema>;
+/** The roles of `TlsSpec` that name a field, in the order the dialog draws them. */
+export declare const TLS_FIELD_ROLES: readonly ["mode", "caFile", "certFile", "keyFile", "keyPassphrase"];
+export type TlsFieldRole = (typeof TLS_FIELD_ROLES)[number];
+export declare const pluginManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    apiVersion: z.ZodString;
+    entry: z.ZodString;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        sql: "sql";
+        cancel: "cancel";
+        schemaTree: "schemaTree";
+        transactions: "transactions";
+        ddl: "ddl";
+        explain: "explain";
+        explainAnalyze: "explainAnalyze";
+        currentNamespace: "currentNamespace";
+        keepAlive: "keepAlive";
+        bulkInsert: "bulkInsert";
+        objects: "objects";
+        serverMessages: "serverMessages";
+        sessions: "sessions";
+        routineCall: "routineCall";
+    }>>;
+    highlight: z.ZodString;
+    connection: z.ZodObject<{
+        fields: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                number: "number";
+                text: "text";
+                select: "select";
+                password: "password";
+                file: "file";
+                checkbox: "checkbox";
+            }>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>>;
+            group: z.ZodOptional<z.ZodEnum<{
+                general: "general";
+                advanced: "advanced";
+            }>>;
+            secret: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        url: z.ZodOptional<z.ZodObject<{
+            schemes: z.ZodArray<z.ZodString>;
+            form: z.ZodEnum<{
+                file: "file";
+                server: "server";
+            }>;
+            parts: z.ZodRecord<z.ZodEnum<{
+                database: "database";
+                path: "path";
+                password: "password";
+                host: "host";
+                port: "port";
+                user: "user";
+            }> & z.core.$partial, z.ZodString>;
+            params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                key: z.ZodString;
+                values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        network: z.ZodOptional<z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodString;
+            connectTimeout: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        tls: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodString;
+            verifyModes: z.ZodArray<z.ZodString>;
+            caFile: z.ZodOptional<z.ZodString>;
+            certFile: z.ZodOptional<z.ZodString>;
+            keyFile: z.ZodOptional<z.ZodString>;
+            keyPassphrase: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PluginManifest = z.infer<typeof pluginManifestSchema>;

package/dist/manifest.js

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { CAPABILITIES } from "./plugin.js";
+import { parseVersion } from "./version.js";
+/** The file that marks a directory as a plugin (decision 005). */
+export const MANIFEST_FILE = "table-craft-plugin.json";
+const PLUGIN_ID = /^[a-z][a-z0-9-]*$/;
+const semver = z.string().refine((text) => parseVersion(text) !== null, { message: "expected major.minor.patch" });
+/**
+ * What the loader reads before executing any plugin code, so an unavailable plugin can still be
+ * named in the UI.
+ */
+export const CONNECTION_FIELD_KINDS = ["text", "number", "password", "file", "select", "checkbox"];
+export const CONNECTION_FIELD_GROUPS = ["general", "advanced"];
+const FIELD_KEY = /^[a-zA-Z][a-zA-Z0-9]*$/;
+/**
+ * One control of the connection form (decision 019). `key` names the config property it fills;
+ * `secret` sends the value to the secret store instead of `datasources.json` (decision 020).
+ */
+export const connectionFieldSchema = z.strictObject({
+    key: z.string().regex(FIELD_KEY, { message: "expected a camelCase config key" }),
+    label: z.string().min(1),
+    kind: z.enum(CONNECTION_FIELD_KINDS),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    required: z.boolean().optional(),
+    placeholder: z.string().optional(),
+    /** The choices of a `select`, in display order. */
+    options: z
+        .array(z.strictObject({ value: z.string(), label: z.string().min(1) }))
+        .min(1)
+        .optional(),
+    group: z.enum(CONNECTION_FIELD_GROUPS).optional(),
+    secret: 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"];
+/** The pieces of a connection URL a field can take; `path` belongs to the `file` form. */
+export const CONNECTION_URL_PARTS = ["host", "port", "database", "user", "password", "path"];
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*$/;
+/**
+ * How a connection URL maps onto the form's fields (decision 055), so the host parses and writes
+ * one without running plugin code. `parts` names the field each piece of the URL fills; a query
+ * parameter fills `key`, its value translated through `values` (compared case-insensitively) when
+ * given, so a value outside them is reported as ignored.
+ */
+export const connectionUrlSchema = z.strictObject({
+    /** Without `://`; the first is the one the host writes. */
+    schemes: z.array(z.string().regex(URL_SCHEME, { message: "expected a lower-case URL scheme" })).min(1),
+    form: z.enum(CONNECTION_URL_FORMS),
+    parts: z.partialRecord(z.enum(CONNECTION_URL_PARTS), z.string().regex(FIELD_KEY)),
+    params: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        key: z.string().regex(FIELD_KEY),
+        values: z.record(z.string(), z.string()).optional(),
+    }))
+        .optional(),
+});
+/**
+ * Which fields hold the server's address (decision 070), so the host can open an SSH tunnel and
+ * hand the plugin `127.0.0.1` and the forwarded port instead. `connectTimeout`, in seconds, bounds
+ * the SSH hop too. Absent: the data source is not reached over the network and offers no tunnel.
+ */
+export const networkSpecSchema = z.strictObject({
+    host: z.string().regex(FIELD_KEY),
+    port: z.string().regex(FIELD_KEY),
+    connectTimeout: z.string().regex(FIELD_KEY).optional(),
+});
+const NETWORK_FIELD_KINDS = { host: "text", port: "number", connectTimeout: "number" };
+function networkFieldsDeclared(connection) {
+    const network = connection.network;
+    if (network === undefined)
+        return true;
+    return Object.keys(NETWORK_FIELD_KINDS).every((role) => {
+        const key = network[role];
+        if (key === undefined)
+            return true;
+        return connection.fields.some((field) => field.key === key && field.kind === NETWORK_FIELD_KINDS[role]);
+    });
+}
+/**
+ * Which fields configure TLS (decision 072), so the dialog groups them under SSL, hints when a CA
+ * file goes unchecked, and main asks for the key passphrase only when the key file is encrypted.
+ * `mode` is the `select` of SSL modes; `verifyModes` are its values that check the server
+ * certificate. Absent: the plugin speaks no TLS the host knows about.
+ */
+export const tlsSpecSchema = z.strictObject({
+    mode: z.string().regex(FIELD_KEY),
+    verifyModes: z.array(z.string().min(1)).min(1),
+    caFile: z.string().regex(FIELD_KEY).optional(),
+    certFile: z.string().regex(FIELD_KEY).optional(),
+    keyFile: z.string().regex(FIELD_KEY).optional(),
+    keyPassphrase: z.string().regex(FIELD_KEY).optional(),
+});
+/** The roles of `TlsSpec` that name a field, in the order the dialog draws them. */
+export const TLS_FIELD_ROLES = ["mode", "caFile", "certFile", "keyFile", "keyPassphrase"];
+function tlsFieldFits(role, field, tls) {
+    switch (role) {
+        case "mode": {
+            const values = new Set((field.options ?? []).map((option) => option.value));
+            return field.kind === "select" && tls.verifyModes.every((mode) => values.has(mode));
+        }
+        case "keyPassphrase":
+            return field.kind === "password" && field.secret === true;
+        default:
+            return field.kind === "file";
+    }
+}
+function tlsFieldsDeclared(connection) {
+    const tls = connection.tls;
+    if (tls === undefined)
+        return true;
+    return TLS_FIELD_ROLES.every((role) => {
+        const key = tls[role];
+        if (key === undefined)
+            return true;
+        const field = connection.fields.find((candidate) => candidate.key === key);
+        return field !== undefined && tlsFieldFits(role, field, tls);
+    });
+}
+export const pluginManifestSchema = z
+    .strictObject({
+    id: z.string().regex(PLUGIN_ID, { message: "expected lower-case letters, digits and dashes" }),
+    name: z.string().min(1),
+    version: semver,
+    apiVersion: semver,
+    /** An ES module, relative to the manifest, whose default export is the `DatasourcePlugin`. */
+    entry: z.string().min(1),
+    capabilities: z.array(z.enum(CAPABILITIES)),
+    /** The highlighter the console uses for this plugin's dialect (decision 008). */
+    highlight: z.string().min(1),
+    /** The connection form, readable without running plugin code (decision 019). */
+    connection: z
+        .strictObject({
+        fields: z.array(connectionFieldSchema).min(1),
+        /** Absent: the form offers no URL to paste and the data source no Copy as URL. */
+        url: connectionUrlSchema.optional(),
+        network: networkSpecSchema.optional(),
+        tls: tlsSpecSchema.optional(),
+    })
+        .refine(networkFieldsDeclared, {
+        message: "network names a field the form does not declare, or one of the wrong kind",
+        path: ["network"],
+    })
+        .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"],
+    }),
+})
+    // 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",
+    path: ["capabilities"],
+})
+    // A plan is of a statement, and Analyse is Explain that also runs it (decision 031).
+    .refine((manifest) => !manifest.capabilities.includes("explain") || manifest.capabilities.includes("sql"), {
+    message: "the explain capability requires sql",
+    path: ["capabilities"],
+})
+    .refine((manifest) => !manifest.capabilities.includes("explainAnalyze") || manifest.capabilities.includes("explain"), { message: "the explainAnalyze capability requires explain", path: ["capabilities"] })
+    // A namespace is switched by a statement, and the switch is told apart by the language (decision 048).
+    .refine((manifest) => !manifest.capabilities.includes("currentNamespace") || manifest.capabilities.includes("sql"), {
+    message: "the currentNamespace capability requires sql",
+    path: ["capabilities"],
+})
+    // An import commits at boundaries it chooses and rolls back the rest (decision 046).
+    .refine((manifest) => !manifest.capabilities.includes("bulkInsert") || manifest.capabilities.includes("transactions"), { message: "the bulkInsert capability requires transactions", path: ["capabilities"] })
+    // 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).
+    .refine((manifest) => !manifest.capabilities.includes("sessions") ||
+    (manifest.capabilities.includes("sql") && manifest.capabilities.includes("schemaTree")), { message: "the sessions capability requires sql and schemaTree", 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/objects.d.ts

@@ -0,0 +1,140 @@
+import type { Relation } from "./catalog.js";
+/** What the database tree can rename or drop (decision 052). */
+export declare const OBJECT_KINDS: readonly ["table", "view", "materializedView", "sequence", "function", "procedure"];
+export type ObjectKind = (typeof OBJECT_KINDS)[number];
+/** One object in a namespace, named as the catalog names it. */
+export interface CatalogObject {
+    readonly kind: ObjectKind;
+    readonly name: string;
+}
+/**
+ * A column of a table design. `original` is the name the column has in the database, null for a
+ * column the design adds, so a rename is told apart from a drop and an add.
+ */
+export interface ColumnDesign {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    /** A SQL expression, written as the column's `DEFAULT` clause takes it; null for none. */
+    readonly default: string | null;
+    readonly autoIncrement: boolean;
+    readonly comment: string | null;
+    readonly original: string | null;
+}
+export interface IndexDesign {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    /** The index's name in the database, null for one the design adds. */
+    readonly original: string | null;
+}
+export interface ForeignKeyDesign {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly target: {
+        readonly path: readonly string[];
+        readonly relation: string;
+        readonly columns: readonly string[];
+    };
+    /** The referential action as the dialect spells it, such as `CASCADE`; null for the default. */
+    readonly onDelete: string | null;
+    readonly onUpdate: string | null;
+    readonly original: string | null;
+}
+export interface CheckDesign {
+    readonly name: string;
+    readonly expression: string;
+    readonly original: string | null;
+}
+/** A table as the Create and Modify Table dialog edits it (decision 052). */
+export interface TableDesign {
+    readonly name: string;
+    readonly comment: string | null;
+    readonly columns: readonly ColumnDesign[];
+    /** Column names in key order; empty for no primary key. */
+    readonly primaryKey: readonly string[];
+    /** The primary key constraint's name in the database, null when the table has none yet. */
+    readonly primaryKeyName: string | null;
+    readonly indexes: readonly IndexDesign[];
+    readonly foreignKeys: readonly ForeignKeyDesign[];
+    readonly checks: readonly CheckDesign[];
+}
+/** One change to the catalog of `path`, which the plugin turns into a `DdlScript`. */
+export type ObjectChange = {
+    readonly kind: "createTable";
+    readonly path: readonly string[];
+    readonly design: TableDesign;
+} | {
+    readonly kind: "alterTable";
+    readonly path: readonly string[];
+    readonly relation: string;
+    readonly design: TableDesign;
+} | {
+    readonly kind: "rename";
+    readonly path: readonly string[];
+    readonly object: CatalogObject;
+    readonly name: string;
+} | {
+    readonly kind: "drop";
+    readonly path: readonly string[];
+    readonly object: CatalogObject;
+    readonly cascade: boolean;
+} | {
+    readonly kind: "truncate";
+    readonly path: readonly string[];
+    readonly relation: string;
+    readonly cascade: boolean;
+}
+/** A schema or database inside `path`; `path` is empty for a top-level one. */
+ | {
+    readonly kind: "createNamespace";
+    readonly path: readonly string[];
+    readonly name: string;
+};
+export type ObjectChangeKind = ObjectChange["kind"];
+/**
+ * The statements for one change. The host runs `prepare` and `finish` outside any transaction on
+ * the session it opens for the change, `statements` in one transaction when `transactional`, then
+ * each of `verify`, which must return no row, before it commits.
+ */
+export interface DdlScript {
+    readonly prepare: readonly string[];
+    readonly statements: readonly string[];
+    readonly verify: readonly string[];
+    readonly finish: readonly string[];
+    readonly transactional: boolean;
+    /** What the preview tells the user before they run it, such as an implicit commit. */
+    readonly notes: readonly string[];
+}
+/** What a dialect lets the tree and the table dialog offer; the UI reads these, never a plugin id. */
+export interface ObjectFeatures {
+    /** Column types the dialog suggests, most common first. */
+    readonly types: readonly string[];
+    readonly checks: boolean;
+    readonly comments: boolean;
+    /** Whether Drop and Truncate take `CASCADE`. */
+    readonly cascade: boolean;
+    readonly truncate: boolean;
+    /** What New ▸ creates inside a namespace, or null when the dialect creates none. */
+    readonly namespaceKind: "schema" | "database" | null;
+    readonly renamable: readonly ObjectKind[];
+    readonly droppable: readonly ObjectKind[];
+}
+/** What the host knows that a script needs: names as the introspector qualifies them, and the table as it is. */
+export interface DdlContext {
+    qualifiedName(path: readonly string[], name: string): string;
+    /** For `alterTable`, the design of the table as the catalog describes it now; otherwise null. */
+    readonly current: TableDesign | null;
+}
+/** Present exactly when the plugin declares `objects` (decision 052). Pure: it never runs SQL. */
+export interface ObjectEditor {
+    readonly features: ObjectFeatures;
+    /** The design of a described table, every name its `original`. */
+    design(relation: Relation): TableDesign;
+    /**
+     * The statements for `change`; an `alterTable` gets only the ones its difference from
+     * `context.current` needs. Throws a `PluginError` coded `statementFailed` saying what to change
+     * when the dialect cannot express it.
+     */
+    script(change: ObjectChange, context: DdlContext): DdlScript;
+}

package/dist/objects.js

@@ -0,0 +1,2 @@
+/** What the database tree can rename or drop (decision 052). */
+export const OBJECT_KINDS = ["table", "view", "materializedView", "sequence", "function", "procedure"];