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

package/dist/tls.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Wording for TLS failures shared by the network plugins (decision 072). Pure: each plugin reads
+ * its files and drives its own driver, and hands the error here to say what did not match.
+ */
+/** Node's codes for a server certificate whose chain the trusted CAs do not vouch for. */
+export declare const TLS_CHAIN_CODES: readonly string[];
+/** Node's code for a certificate that does not name the host it was checked against. */
+export declare const TLS_HOST_CODE = "ERR_TLS_CERT_ALTNAME_INVALID";
+/** `path` with a leading `~` replaced by `home`, as a shell would; any other path unchanged. */
+export declare function homeExpanded(path: string, home: string): string;
+/** What a verifying connection checked the server certificate against. */
+export interface TlsVerification {
+    /** The CA file field's form label, such as `SSL root certificate`. */
+    readonly caLabel: string;
+    /** The CA file's path; null when the system's trusted CAs were used. */
+    readonly caPath: string | null;
+    /** The host name the certificate had to carry. */
+    readonly host: string;
+}
+/**
+ * Says what a verification failure did not match, or null when `cause` is not one: the CA file
+ * (or the system's CAs) for a chain error, the host name for a name mismatch.
+ */
+export declare function tlsFailureMessage(cause: unknown, verification: TlsVerification): string | null;
+/** Words a failure to read one of the TLS files, naming the field and the path. */
+export declare function tlsFileMessage(label: string, path: string, cause: unknown): string;
+/** Whether a PEM private key needs a passphrase: PKCS#8 encrypted, or traditional with `Proc-Type`. */
+export declare function tlsKeyIsEncrypted(text: string): boolean;
+/**
+ * Words a client key or certificate OpenSSL refused, naming the key file. Any failure on an
+ * `encrypted` key is put down to the passphrase, since OpenSSL's codes for it vary by version.
+ */
+export declare function tlsKeyMessage(label: string, path: string, cause: unknown, encrypted?: boolean): string;

package/dist/tls.js

@@ -0,0 +1,118 @@
+/**
+ * Wording for TLS failures shared by the network plugins (decision 072). Pure: each plugin reads
+ * its files and drives its own driver, and hands the error here to say what did not match.
+ */
+/** Node's codes for a server certificate whose chain the trusted CAs do not vouch for. */
+export const TLS_CHAIN_CODES = [
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "CERT_SIGNATURE_FAILURE",
+    "CERT_UNTRUSTED",
+];
+/** Node's codes for a server certificate outside its validity dates. */
+const TLS_DATE_CODES = ["CERT_HAS_EXPIRED", "CERT_NOT_YET_VALID"];
+/** Node's code for a certificate that does not name the host it was checked against. */
+export const TLS_HOST_CODE = "ERR_TLS_CERT_ALTNAME_INVALID";
+/** Node's codes for a private key it could not decrypt with the passphrase given, or without one. */
+const BAD_DECRYPT_CODES = [
+    "ERR_OSSL_BAD_DECRYPT",
+    "ERR_OSSL_EVP_BAD_DECRYPT",
+    "ERR_MISSING_PASSPHRASE",
+];
+const HOME_PREFIX = /^~(?=$|[/\\])/;
+/** `path` with a leading `~` replaced by `home`, as a shell would; any other path unchanged. */
+export function homeExpanded(path, home) {
+    return path.replace(HOME_PREFIX, () => home);
+}
+const FILE_REASONS = {
+    ENOENT: "the file does not exist",
+    EACCES: "permission denied",
+    EPERM: "permission denied",
+    EISDIR: "it is a folder, not a file",
+};
+function codeOf(cause) {
+    if (typeof cause !== "object" || cause === null || !("code" in cause))
+        return null;
+    return typeof cause.code === "string" ? cause.code : null;
+}
+function reasonOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * OpenSSL's `X509_verify_cert_error_string` for each code, lower-cased and with hyphens as spaces:
+ * OpenSSL 3 writes "self-signed", BoringSSL (Electron) "self signed".
+ */
+const VERIFY_REASONS = {
+    "unable to verify the first certificate": "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "unable to get issuer certificate": "UNABLE_TO_GET_ISSUER_CERT",
+    "unable to get local issuer certificate": "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "self signed certificate in certificate chain": "SELF_SIGNED_CERT_IN_CHAIN",
+    "self signed certificate": "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "certificate signature failure": "CERT_SIGNATURE_FAILURE",
+    "certificate not trusted": "CERT_UNTRUSTED",
+    "certificate has expired": "CERT_HAS_EXPIRED",
+    "certificate is not yet valid": "CERT_NOT_YET_VALID",
+};
+const KNOWN_CODES = [...TLS_CHAIN_CODES, ...TLS_DATE_CODES, TLS_HOST_CODE];
+/**
+ * Node's code for a TLS failure. A driver may overwrite it (mysql2 sets `HANDSHAKE_SSL_ERROR`,
+ * `lib/commands/client_handshake.js`), so the error is recognised by what survives: the
+ * `reason`, `host` and `cert` of a `checkServerIdentity` error, or OpenSSL's message.
+ */
+function tlsCodeOf(cause) {
+    const code = codeOf(cause);
+    if (code !== null && KNOWN_CODES.includes(code))
+        return code;
+    if (typeof cause !== "object" || cause === null)
+        return null;
+    if ("reason" in cause && "host" in cause && "cert" in cause)
+        return TLS_HOST_CODE;
+    return VERIFY_REASONS[reasonOf(cause).toLowerCase().replaceAll("-", " ")] ?? null;
+}
+/**
+ * Says what a verification failure did not match, or null when `cause` is not one: the CA file
+ * (or the system's CAs) for a chain error, the host name for a name mismatch.
+ */
+export function tlsFailureMessage(cause, verification) {
+    const code = tlsCodeOf(cause);
+    if (code === null)
+        return null;
+    const reason = reasonOf(cause);
+    if (code === TLS_HOST_CODE) {
+        return `The server certificate is not valid for host ${verification.host} (${reason}). Use Verify CA to check the certificate without its host name.`;
+    }
+    if (TLS_DATE_CODES.includes(code))
+        return `The server certificate is outside its validity dates (${reason}).`;
+    if (!TLS_CHAIN_CODES.includes(code))
+        return null;
+    const { caLabel, caPath } = verification;
+    if (caPath === null) {
+        return `The server certificate is not signed by a CA this system trusts (${reason}). Choose the server's CA file as the ${caLabel}.`;
+    }
+    return `The server certificate is not signed by the CA in ${caPath} (${caLabel}): ${reason}.`;
+}
+/** Words a failure to read one of the TLS files, naming the field and the path. */
+export function tlsFileMessage(label, path, cause) {
+    const code = codeOf(cause);
+    const reason = (code === null ? undefined : FILE_REASONS[code]) ?? reasonOf(cause);
+    return `Cannot read the ${label} ${path}: ${reason}.`;
+}
+const ENCRYPTED_KEY = /-----BEGIN ENCRYPTED PRIVATE KEY-----|^Proc-Type: 4,ENCRYPTED/m;
+/** Whether a PEM private key needs a passphrase: PKCS#8 encrypted, or traditional with `Proc-Type`. */
+export function tlsKeyIsEncrypted(text) {
+    return ENCRYPTED_KEY.test(text);
+}
+/**
+ * Words a client key or certificate OpenSSL refused, naming the key file. Any failure on an
+ * `encrypted` key is put down to the passphrase, since OpenSSL's codes for it vary by version.
+ */
+export function tlsKeyMessage(label, path, cause, encrypted = false) {
+    const code = codeOf(cause);
+    if (encrypted || (code !== null && BAD_DECRYPT_CODES.includes(code))) {
+        return `Cannot decrypt the ${label} ${path}: the passphrase is wrong or missing.`;
+    }
+    return `Cannot use the ${label} ${path}: ${reasonOf(cause)}.`;
+}

package/dist/url.d.ts

@@ -0,0 +1,52 @@
+import type { ConnectionFieldKind, ConnectionUrlForm, ConnectionUrlPart } from "./manifest.js";
+/** A form value as `datasources.json` holds it. */
+export type ConnectionValue = string | number | boolean;
+/** What a pasted connection URL fills in (decision 055). */
+export interface ParsedConnectionUrl {
+    /** Field key to value, for the fields the URL names; secrets are not among them. */
+    readonly values: Readonly<Record<string, ConnectionValue>>;
+    /** Secret field key to value, such as the password; for the secret store, never `datasources.json`. */
+    readonly secrets: Readonly<Record<string, string>>;
+    /** The query parameters, or their values, no field takes, as the user should see them listed. */
+    readonly ignored: readonly string[];
+}
+/** The text is not a connection URL this plugin reads; the message says what it expected. */
+export declare class ConnectionUrlError extends Error {
+    readonly name = "ConnectionUrlError";
+}
+/** A manifest's `connection.url`, read-only so a host's copy of it serves as well. */
+export interface ConnectionUrlSpec {
+    readonly schemes: readonly string[];
+    readonly form: ConnectionUrlForm;
+    readonly parts: Readonly<Partial<Record<ConnectionUrlPart, string>>>;
+    readonly params?: readonly {
+        readonly name: string;
+        readonly key: string;
+        readonly values?: Readonly<Record<string, string>> | undefined;
+    }[] | undefined;
+}
+interface UrlField {
+    readonly key: string;
+    readonly kind: ConnectionFieldKind;
+    readonly default?: ConnectionValue | undefined;
+    readonly secret?: boolean | undefined;
+}
+/** The part of a manifest the URL functions read: its connection fields and URL. */
+export interface ConnectionForm {
+    readonly connection: {
+        readonly fields: readonly UrlField[];
+        readonly url?: ConnectionUrlSpec | undefined;
+    };
+}
+/**
+ * Reads `text` as the plugin's connection URL: `scheme://user:password@host:port/database?params`
+ * for a server, or a path, bare or as a `sqlite:`/`file:` URL, for a file. A `jdbc:` prefix is
+ * dropped. Throws `ConnectionUrlError` when it is none.
+ */
+export declare function parseConnectionUrl(form: ConnectionForm, text: string): ParsedConnectionUrl;
+/**
+ * The connection URL of `config`, in the plugin's first scheme. Never carries a secret field, so
+ * the result is safe to copy, show and log; params equal to their field's default are left out.
+ */
+export declare function formatConnectionUrl(form: ConnectionForm, config: Readonly<Record<string, unknown>>): string;
+export {};

package/dist/url.js

@@ -0,0 +1,219 @@
+/** The text is not a connection URL this plugin reads; the message says what it expected. */
+export class ConnectionUrlError extends Error {
+    name = "ConnectionUrlError";
+}
+/** Tools written for the JVM prefix their URLs with it; the rest of the URL is the usual one. */
+const JDBC_PREFIX = "jdbc:";
+const MEMORY_PATH = ":memory:";
+const SCHEME = /^([a-zA-Z][a-zA-Z0-9+.-]*):/;
+const WINDOWS_DRIVE_PATH = /^\/[A-Za-z]:[/\\]/;
+const LEADING_SLASHES = /^\/+/;
+const LOCAL_HOSTS = new Set(["", "localhost"]);
+/** libpq's names for the parts of the URL, accepted as query parameters by every server form. */
+const PART_PARAMS = {
+    host: "host",
+    port: "port",
+    dbname: "database",
+    database: "database",
+    user: "user",
+    password: "password",
+};
+function urlOf(form) {
+    const url = form.connection.url;
+    if (url === undefined)
+        throw new ConnectionUrlError("This data source type has no connection URL.");
+    return url;
+}
+function schemeList(url) {
+    const written = url.schemes.map((scheme) => (url.form === "server" ? `${scheme}://` : `${scheme}:`));
+    return written.length === 1 ? (written[0] ?? "") : `${written.slice(0, -1).join(", ")} or ${written.at(-1) ?? ""}`;
+}
+function decoded(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        throw new ConnectionUrlError(`"${text}" is not valid percent-encoding; write % as %25.`);
+    }
+}
+function fieldOf(form, key) {
+    return form.connection.fields.find((field) => field.key === key);
+}
+function coerced(field, raw, label) {
+    if (field?.kind === "number") {
+        const value = Number(raw);
+        if (raw.trim() === "" || !Number.isFinite(value))
+            throw new ConnectionUrlError(`The ${label} "${raw}" is not a number.`);
+        return value;
+    }
+    if (field?.kind === "checkbox")
+        return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+    return raw;
+}
+class Collected {
+    form;
+    url;
+    values = {};
+    secrets = {};
+    ignored = [];
+    constructor(form, url) {
+        this.form = form;
+        this.url = url;
+    }
+    part(part, raw) {
+        const key = this.url.parts[part];
+        if (key === undefined || raw === "")
+            return;
+        const field = fieldOf(this.form, key);
+        if (field?.secret === true)
+            this.secrets[key] = raw;
+        else
+            this.values[key] = coerced(field, raw, part);
+    }
+    param(name, raw) {
+        const lower = name.toLowerCase();
+        const param = this.url.params?.find((candidate) => candidate.name.toLowerCase() === lower);
+        if (param === undefined) {
+            const part = this.url.form === "server" ? PART_PARAMS[lower] : undefined;
+            if (part !== undefined && this.url.parts[part] !== undefined)
+                this.part(part, raw);
+            else
+                this.ignored.push(name);
+            return;
+        }
+        if (param.values === undefined) {
+            this.values[param.key] = coerced(fieldOf(this.form, param.key), raw, name);
+            return;
+        }
+        const match = Object.entries(param.values).find(([value]) => value.toLowerCase() === raw.toLowerCase());
+        if (match === undefined)
+            this.ignored.push(`${name}=${raw}`);
+        else
+            this.values[param.key] = match[1];
+    }
+    query(search) {
+        for (const [name, value] of new URLSearchParams(search))
+            this.param(name, value);
+    }
+    done() {
+        return { values: this.values, secrets: this.secrets, ignored: this.ignored };
+    }
+}
+function parseServer(form, url, text) {
+    const scheme = SCHEME.exec(text)?.[1]?.toLowerCase();
+    if (scheme === undefined || !url.schemes.includes(scheme) || !text.slice(scheme.length + 1).startsWith("//")) {
+        throw new ConnectionUrlError(`Expected a URL starting with ${schemeList(url)}.`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        throw new ConnectionUrlError(`That is not a valid ${scheme}:// URL; check the port is a number and special characters are percent-encoded.`);
+    }
+    const collected = new Collected(form, url);
+    collected.part("host", decoded(parsed.hostname.replace(/^\[(.*)\]$/, "$1")));
+    collected.part("port", parsed.port);
+    collected.part("database", decoded(parsed.pathname.replace(LEADING_SLASHES, "")));
+    collected.part("user", decoded(parsed.username));
+    collected.part("password", decoded(parsed.password));
+    collected.query(parsed.search);
+    return collected.done();
+}
+function parseFile(form, url, text) {
+    const collected = new Collected(form, url);
+    const scheme = SCHEME.exec(text)?.[1]?.toLowerCase();
+    // One letter before the colon is a Windows drive, not a scheme.
+    if (scheme === undefined || scheme.length === 1 || text === MEMORY_PATH) {
+        collected.part("path", text);
+        return collected.done();
+    }
+    if (!url.schemes.includes(scheme)) {
+        throw new ConnectionUrlError(`Expected a file path, or a URL starting with ${schemeList(url)}.`);
+    }
+    let rest = text.slice(scheme.length + 1);
+    const queryAt = rest.search(/[?#]/);
+    if (queryAt >= 0) {
+        const query = rest.slice(queryAt);
+        rest = rest.slice(0, queryAt);
+        if (query.startsWith("?"))
+            collected.query(query.split("#")[0] ?? "");
+    }
+    if (rest.startsWith("//")) {
+        const authorityEnd = rest.indexOf("/", 2);
+        const authority = authorityEnd < 0 ? rest.slice(2) : rest.slice(2, authorityEnd);
+        if (authority === MEMORY_PATH)
+            rest = MEMORY_PATH;
+        else if (!LOCAL_HOSTS.has(authority.toLowerCase())) {
+            throw new ConnectionUrlError(`"${authority}" names another machine; a file URL reads a local file.`);
+        }
+        else
+            rest = authorityEnd < 0 ? "" : rest.slice(authorityEnd).replace(LEADING_SLASHES, "/");
+    }
+    const path = decoded(rest);
+    collected.part("path", WINDOWS_DRIVE_PATH.test(path) ? path.slice(1) : path);
+    return collected.done();
+}
+/**
+ * Reads `text` as the plugin's connection URL: `scheme://user:password@host:port/database?params`
+ * for a server, or a path, bare or as a `sqlite:`/`file:` URL, for a file. A `jdbc:` prefix is
+ * dropped. Throws `ConnectionUrlError` when it is none.
+ */
+export function parseConnectionUrl(form, text) {
+    const url = urlOf(form);
+    let trimmed = text.trim();
+    if (trimmed.toLowerCase().startsWith(JDBC_PREFIX))
+        trimmed = trimmed.slice(JDBC_PREFIX.length);
+    if (trimmed === "")
+        throw new ConnectionUrlError(`Expected a URL starting with ${schemeList(url)}.`);
+    return url.form === "server" ? parseServer(form, url, trimmed) : parseFile(form, url, trimmed);
+}
+function isConnectionValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function written(value) {
+    return String(value);
+}
+function encodedPath(path) {
+    return encodeURI(path).replaceAll("?", "%3F").replaceAll("#", "%23");
+}
+/**
+ * The connection URL of `config`, in the plugin's first scheme. Never carries a secret field, so
+ * the result is safe to copy, show and log; params equal to their field's default are left out.
+ */
+export function formatConnectionUrl(form, config) {
+    const url = urlOf(form);
+    const scheme = url.schemes[0] ?? "";
+    const valueOf = (part) => {
+        const key = url.parts[part];
+        if (key === undefined || fieldOf(form, key)?.secret === true)
+            return "";
+        const value = config[key];
+        return isConnectionValue(value) ? written(value) : "";
+    };
+    const params = new URLSearchParams();
+    for (const param of url.params ?? []) {
+        const value = config[param.key];
+        const field = fieldOf(form, param.key);
+        if (field?.secret === true || !isConnectionValue(value) || value === "" || value === field?.default)
+            continue;
+        const text = param.values === undefined
+            ? written(value)
+            : Object.entries(param.values).find(([, mapped]) => mapped === value)?.[0];
+        if (text !== undefined)
+            params.append(param.name, text);
+    }
+    const query = params.size === 0 ? "" : `?${params.toString()}`;
+    if (url.form === "file") {
+        const path = valueOf("path");
+        if (path === MEMORY_PATH || !path.startsWith("/"))
+            return `${scheme}:${encodedPath(path)}${query}`;
+        return `${scheme}://${encodedPath(path)}${query}`;
+    }
+    const user = valueOf("user");
+    const host = valueOf("host");
+    const port = valueOf("port");
+    const database = valueOf("database");
+    const authority = `${user === "" ? "" : `${encodeURIComponent(user)}@`}${host.includes(":") ? `[${host}]` : encodeURIComponent(host)}${port === "" ? "" : `:${port}`}`;
+    return `${scheme}://${authority}${database === "" ? "" : `/${encodeURIComponent(database)}`}${query}`;
+}

package/dist/values.d.ts

@@ -0,0 +1,44 @@
+/** Bytes shown of a binary value; the rest stays in the database (decision 009). */
+export declare const BYTES_PREVIEW_LENGTH = 32;
+export interface BigIntValue {
+    readonly kind: "bigint";
+    readonly value: string;
+}
+export interface BytesValue {
+    readonly kind: "bytes";
+    /**
+     * Lower-case hex of the first `BYTES_PREVIEW_LENGTH` bytes, or of every byte when the statement
+     * ran with `ExecuteOptions.fullBytes`; the value is complete exactly when `preview.length` is
+     * twice `length`.
+     */
+    readonly preview: string;
+    readonly length: number;
+}
+export interface JsonValue {
+    readonly kind: "json";
+    readonly text: string;
+}
+export interface DateValue {
+    readonly kind: "date";
+    readonly iso: string;
+}
+/**
+ * One cell as it crosses a process boundary. Anything structured clone would mangle, or that is
+ * too large to ship whole, is tagged.
+ */
+export type WireValue = null | boolean | number | string | BigIntValue | BytesValue | JsonValue | DateValue;
+/**
+ * What a column's values are. The grid sorts, aligns and draws its header glyph by this. The host
+ * reads it from the type name unless the plugin names it on the `Column` (decision 101).
+ */
+export type TypeClass = "integer" | "float" | "decimal" | "boolean" | "temporal" | "json" | "bytes" | "text";
+export interface WireValueOptions {
+    /** Ship every byte of a binary value instead of the preview (`ExecuteOptions.fullBytes`). */
+    readonly fullBytes?: boolean;
+}
+/** A binary value as it crosses the wire: the preview, or every byte with `fullBytes`. */
+export declare function toBytesValue(bytes: Uint8Array, options?: WireValueOptions): BytesValue;
+/** A 64-bit integer as a number when it is exact in a double, tagged otherwise. */
+export declare function toWireInteger(value: bigint | string): number | BigIntValue;
+/** Converts what a JavaScript driver typically returns into a `WireValue`. */
+export declare function toWireValue(value: unknown, options?: WireValueOptions): WireValue;

package/dist/values.js

@@ -0,0 +1,44 @@
+/** Bytes shown of a binary value; the rest stays in the database (decision 009). */
+export const BYTES_PREVIEW_LENGTH = 32;
+const HEX_RADIX = 16;
+const HEX_BYTE_WIDTH = 2;
+const BYTE_VALUES = 256;
+const HEX_DIGITS = Array.from({ length: BYTE_VALUES }, (_, byte) => byte.toString(HEX_RADIX).padStart(HEX_BYTE_WIDTH, "0"));
+function toHex(bytes) {
+    const digits = new Array(bytes.byteLength);
+    for (let index = 0; index < bytes.byteLength; index += 1)
+        digits[index] = HEX_DIGITS[bytes[index] ?? 0] ?? "";
+    return digits.join("");
+}
+/** A binary value as it crosses the wire: the preview, or every byte with `fullBytes`. */
+export function toBytesValue(bytes, options = {}) {
+    const shown = options.fullBytes === true ? bytes : bytes.subarray(0, BYTES_PREVIEW_LENGTH);
+    return { kind: "bytes", preview: toHex(shown), length: bytes.byteLength };
+}
+/** A 64-bit integer as a number when it is exact in a double, tagged otherwise. */
+export function toWireInteger(value) {
+    const exact = BigInt(value);
+    if (exact >= BigInt(Number.MIN_SAFE_INTEGER) && exact <= BigInt(Number.MAX_SAFE_INTEGER))
+        return Number(exact);
+    return { kind: "bigint", value: exact.toString() };
+}
+/** Converts what a JavaScript driver typically returns into a `WireValue`. */
+export function toWireValue(value, options = {}) {
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case "boolean":
+        case "number":
+        case "string":
+            return value;
+        case "bigint":
+            return { kind: "bigint", value: value.toString() };
+        default:
+            break;
+    }
+    if (value instanceof Uint8Array)
+        return toBytesValue(value, options);
+    if (value instanceof Date)
+        return { kind: "date", iso: value.toISOString() };
+    return { kind: "json", text: JSON.stringify(value) };
+}

package/dist/version.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
+ * major and an older or equal minor. Typed `string` so a bump does not change the API report.
+ */
+export declare const API_VERSION: string;
+interface Version {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+/** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
+export declare function parseVersion(text: string): Version | null;
+/**
+ * Why a plugin built against `apiVersion` cannot load on `hostVersion`: it needs a `newer` host
+ * (a later minor, or a later major), it was built for an `olderMajor`, or the version is `invalid`.
+ * Null when it loads.
+ */
+export type Incompatibility = "newer" | "olderMajor" | "invalid";
+export declare function incompatibility(apiVersion: string, hostVersion?: string): Incompatibility | null;
+/** Whether a plugin built against `apiVersion` can be loaded by this `API_VERSION`, by semver. */
+export declare function isCompatible(apiVersion: string, hostVersion?: string): boolean;
+export {};

package/dist/version.js

@@ -0,0 +1,29 @@
+/**
+ * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
+ * major and an older or equal minor. Typed `string` so a bump does not change the API report.
+ */
+export const API_VERSION = "1.1.0";
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
+export function parseVersion(text) {
+    const match = SEMVER.exec(text);
+    if (match === null)
+        return null;
+    const [, major, minor, patch] = match;
+    return { major: Number(major), minor: Number(minor), patch: Number(patch) };
+}
+export function incompatibility(apiVersion, hostVersion = API_VERSION) {
+    const plugin = parseVersion(apiVersion);
+    const host = parseVersion(hostVersion);
+    if (plugin === null || host === null)
+        return "invalid";
+    if (plugin.major < host.major)
+        return "olderMajor";
+    if (plugin.major > host.major || plugin.minor > host.minor)
+        return "newer";
+    return null;
+}
+/** Whether a plugin built against `apiVersion` can be loaded by this `API_VERSION`, by semver. */
+export function isCompatible(apiVersion, hostVersion = API_VERSION) {
+    return incompatibility(apiVersion, hostVersion) === null;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@tablecraft-app/plugin-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "The datasource plugin contract for TableCraft",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tranphucbol/table-craft.git",
+    "directory": "packages/plugin-api"
+  },
+  "dependencies": {
+    "sql-formatter": "^15.9.0",
+    "zod": "^4.1.0"
+  },
+  "peerDependencies": {
+    "vitest": "^4.1.11"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sql": {
+      "types": "./dist/sql/index.d.ts",
+      "default": "./dist/sql/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  }
+}