@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/schema-plan.d.ts

@@ -0,0 +1,98 @@
+import type { ApplicationSchemaIdentityV0, NormalizedApplicationManifestV0, ScalarType } from './types.js';
+export declare const SCHEMA_PROTOCOL: "xeer.schema.v0";
+export type NormalizedDatabaseSchemaV0 = NormalizedApplicationManifestV0['database'];
+/**
+ * Field keys with no dedicated step. Each one changes what the column's DDL says, so a change to any
+ * of them has to reach the plan — otherwise a schema whose hash moved would produce no steps and be
+ * classified as an unchanged schema that somehow needs a version bump.
+ */
+export declare const FIELD_ATTRIBUTES: readonly ["collate", "default", "enum", "generated", "onDelete", "onUpdate", "table", "unique"];
+export type FieldAttribute = (typeof FIELD_ATTRIBUTES)[number];
+export type SchemaPlanStepV0 = {
+    kind: 'table.add';
+    table: string;
+} | {
+    kind: 'table.remove';
+    table: string;
+} | {
+    kind: 'table.constraint';
+    table: string;
+    constraint: 'unique' | 'checks';
+    from: unknown;
+    to: unknown;
+} | {
+    kind: 'field.add';
+    table: string;
+    field: string;
+    optional: boolean;
+} | {
+    kind: 'field.remove';
+    table: string;
+    field: string;
+} | {
+    kind: 'field.type';
+    table: string;
+    field: string;
+    from: ScalarType;
+    to: ScalarType;
+} | {
+    kind: 'field.optional';
+    table: string;
+    field: string;
+    from: boolean;
+    to: boolean;
+} | {
+    kind: 'field.maxLength';
+    table: string;
+    field: string;
+    from: number | null;
+    to: number | null;
+} | {
+    kind: 'field.attribute';
+    table: string;
+    field: string;
+    attribute: FieldAttribute;
+    from: unknown;
+    to: unknown;
+} | {
+    kind: 'index.add';
+    table: string;
+    index: string;
+    fields: string[];
+} | {
+    kind: 'index.remove';
+    table: string;
+    index: string;
+    fields: string[];
+} | {
+    kind: 'index.change';
+    table: string;
+    index: string;
+    from: string[];
+    to: string[];
+} | {
+    kind: 'index.attribute';
+    table: string;
+    index: string;
+    attribute: 'unique' | 'where';
+    from: unknown;
+    to: unknown;
+} | {
+    kind: 'unknown.change';
+    path: string;
+};
+export interface SchemaPlanV0 {
+    protocol: typeof SCHEMA_PROTOCOL;
+    application: string;
+    from: ApplicationSchemaIdentityV0;
+    to: ApplicationSchemaIdentityV0;
+    classification: 'unchanged' | 'compatible' | 'incompatible';
+    steps: SchemaPlanStepV0[];
+    requiresReset: boolean;
+}
+export type SchemaPlanningErrorCode = 'schema_version_regressed' | 'schema_version_unchanged' | 'schema_version_skipped';
+export declare class SchemaPlanningError extends Error {
+    readonly code: SchemaPlanningErrorCode;
+    constructor(code: SchemaPlanningErrorCode, message: string);
+}
+export declare function planSchemaChangeWithIdentities(application: string, fromSchema: NormalizedDatabaseSchemaV0, from: ApplicationSchemaIdentityV0, toSchema: NormalizedDatabaseSchemaV0, to: ApplicationSchemaIdentityV0): SchemaPlanV0;

package/vendor/spec/schema-plan.js

@@ -0,0 +1,194 @@
+import { indexTermLabel, normalizedIndex } from './table-ddl.js';
+export const SCHEMA_PROTOCOL = 'xeer.schema.v0';
+/**
+ * Field keys with no dedicated step. Each one changes what the column's DDL says, so a change to any
+ * of them has to reach the plan — otherwise a schema whose hash moved would produce no steps and be
+ * classified as an unchanged schema that somehow needs a version bump.
+ */
+export const FIELD_ATTRIBUTES = Object.freeze([
+    'collate', 'default', 'enum', 'generated', 'onDelete', 'onUpdate', 'table', 'unique',
+]);
+export class SchemaPlanningError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SchemaPlanningError';
+    }
+}
+function sameArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function maxLengthStep(table, field, from, to) {
+    if (from === to)
+        return null;
+    return { kind: 'field.maxLength', table, field, from: from ?? null, to: to ?? null };
+}
+function tableSteps(tableName, from, to) {
+    const steps = [];
+    const fromFields = new Set(Object.keys(from.fields));
+    const toFields = new Set(Object.keys(to.fields));
+    for (const field of [...fromFields].filter((name) => !toFields.has(name)).sort()) {
+        steps.push({ kind: 'field.remove', table: tableName, field });
+    }
+    for (const field of [...toFields].filter((name) => !fromFields.has(name)).sort()) {
+        steps.push({ kind: 'field.add', table: tableName, field, optional: to.fields[field].optional ?? false });
+    }
+    for (const field of [...fromFields].filter((name) => toFields.has(name)).sort()) {
+        const before = from.fields[field];
+        const after = to.fields[field];
+        if (before.type !== after.type) {
+            steps.push({ kind: 'field.type', table: tableName, field, from: before.type, to: after.type });
+        }
+        const beforeOptional = before.optional ?? false;
+        const afterOptional = after.optional ?? false;
+        if (beforeOptional !== afterOptional) {
+            steps.push({ kind: 'field.optional', table: tableName, field, from: beforeOptional, to: afterOptional });
+        }
+        const length = maxLengthStep(tableName, field, before.maxLength, after.maxLength);
+        if (length)
+            steps.push(length);
+        for (const attribute of FIELD_ATTRIBUTES) {
+            if (sameUnknownValue(before[attribute], after[attribute]))
+                continue;
+            steps.push({ kind: 'field.attribute', table: tableName, field, attribute,
+                from: before[attribute] ?? null, to: after[attribute] ?? null });
+        }
+    }
+    for (const constraint of ['unique', 'checks']) {
+        if (sameUnknownValue(from[constraint], to[constraint]))
+            continue;
+        steps.push({ kind: 'table.constraint', table: tableName, constraint,
+            from: from[constraint] ?? null, to: to[constraint] ?? null });
+    }
+    // Indexes are compared through their normalized form, so `["slug"]` and `{ columns: ["slug"] }`
+    // are one index written two ways rather than a change from one to the other.
+    const terms = (index) => normalizedIndex(index).columns.map(indexTermLabel);
+    const fromIndexes = from.indexes ?? {};
+    const toIndexes = to.indexes ?? {};
+    const fromNames = new Set(Object.keys(fromIndexes));
+    const toNames = new Set(Object.keys(toIndexes));
+    for (const index of [...fromNames].filter((name) => !toNames.has(name)).sort()) {
+        steps.push({ kind: 'index.remove', table: tableName, index, fields: terms(fromIndexes[index]) });
+    }
+    for (const index of [...toNames].filter((name) => !fromNames.has(name)).sort()) {
+        steps.push({ kind: 'index.add', table: tableName, index, fields: terms(toIndexes[index]) });
+    }
+    for (const index of [...fromNames].filter((name) => toNames.has(name)).sort()) {
+        const before = normalizedIndex(fromIndexes[index]);
+        const after = normalizedIndex(toIndexes[index]);
+        if (!sameArray(terms(fromIndexes[index]), terms(toIndexes[index]))) {
+            steps.push({ kind: 'index.change', table: tableName, index,
+                from: terms(fromIndexes[index]), to: terms(toIndexes[index]) });
+        }
+        for (const attribute of ['unique', 'where']) {
+            if (before[attribute] === after[attribute])
+                continue;
+            steps.push({ kind: 'index.attribute', table: tableName, index, attribute,
+                from: before[attribute], to: after[attribute] });
+        }
+    }
+    return steps;
+}
+/**
+ * Whether a step leaves the rows already stored valid. Nothing in the extended vocabulary does,
+ * with one exception: a DEFAULT decides what a later insert that omits the column receives and says
+ * nothing about the rows already there, so changing one cannot invalidate them.
+ */
+function isCompatible(step) {
+    if (step.kind === 'table.add' || step.kind === 'index.add')
+        return true;
+    if (step.kind === 'field.add')
+        return step.optional;
+    if (step.kind === 'field.optional')
+        return step.from === false && step.to === true;
+    if (step.kind === 'field.maxLength') {
+        return step.from !== null && (step.to === null || step.to > step.from);
+    }
+    if (step.kind === 'field.attribute')
+        return step.attribute === 'default';
+    return false;
+}
+function sameUnknownValue(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== typeof right || left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length
+            && left.every((value, index) => sameUnknownValue(value, right[index]));
+    }
+    if (typeof left !== 'object')
+        return false;
+    const before = left;
+    const after = right;
+    const beforeKeys = Object.keys(before).sort();
+    const afterKeys = Object.keys(after).sort();
+    return sameArray(beforeKeys, afterKeys)
+        && beforeKeys.every((key) => sameUnknownValue(before[key], after[key]));
+}
+function unknownKeySteps(path, from, to, allowed) {
+    const before = typeof from === 'object' && from !== null && !Array.isArray(from)
+        ? from : {};
+    const after = typeof to === 'object' && to !== null && !Array.isArray(to)
+        ? to : {};
+    const known = new Set(allowed);
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+        .filter((key) => !known.has(key))
+        .sort()
+        .filter((key) => {
+        const beforeHas = Object.hasOwn(before, key);
+        const afterHas = Object.hasOwn(after, key);
+        return beforeHas !== afterHas || !sameUnknownValue(before[key], after[key]);
+    })
+        .map((key) => ({ kind: 'unknown.change', path: `${path}.${key}` }));
+}
+function unknownSchemaSteps(fromSchema, toSchema) {
+    const steps = unknownKeySteps('database', fromSchema, toSchema, ['version', 'tables']);
+    const tableNames = [...new Set([...Object.keys(fromSchema.tables), ...Object.keys(toSchema.tables)])].sort();
+    for (const tableName of tableNames) {
+        const beforeTable = fromSchema.tables[tableName];
+        const afterTable = toSchema.tables[tableName];
+        steps.push(...unknownKeySteps(`database.tables.${tableName}`, beforeTable, afterTable, ['fields', 'indexes', 'unique', 'checks']));
+        const beforeFields = beforeTable?.fields ?? {};
+        const afterFields = afterTable?.fields ?? {};
+        const fieldNames = [...new Set([...Object.keys(beforeFields), ...Object.keys(afterFields)])].sort();
+        for (const fieldName of fieldNames) {
+            steps.push(...unknownKeySteps(`database.tables.${tableName}.fields.${fieldName}`, beforeFields[fieldName], afterFields[fieldName], ['type', 'optional', 'maxLength', ...FIELD_ATTRIBUTES]));
+        }
+    }
+    return steps;
+}
+export function planSchemaChangeWithIdentities(application, fromSchema, from, toSchema, to) {
+    const unknownSteps = unknownSchemaSteps(fromSchema, toSchema);
+    if (to.applicationSchemaVersion < from.applicationSchemaVersion) {
+        throw new SchemaPlanningError('schema_version_regressed', `Application schema version cannot regress from ${from.applicationSchemaVersion} to ${to.applicationSchemaVersion}.`);
+    }
+    if (to.applicationSchemaVersion === from.applicationSchemaVersion
+        && (to.schemaHash !== from.schemaHash || unknownSteps.length > 0)) {
+        throw new SchemaPlanningError('schema_version_unchanged', `Application schema changed without increasing database.version from ${from.applicationSchemaVersion}.`);
+    }
+    if (to.applicationSchemaVersion > from.applicationSchemaVersion + 1) {
+        throw new SchemaPlanningError('schema_version_skipped', `Application schema version must advance one step from ${from.applicationSchemaVersion}; received ${to.applicationSchemaVersion}.`);
+    }
+    if (to.schemaHash === from.schemaHash && unknownSteps.length === 0
+        && to.applicationSchemaVersion === from.applicationSchemaVersion) {
+        return { protocol: SCHEMA_PROTOCOL, application, from, to,
+            classification: 'unchanged', steps: [], requiresReset: false };
+    }
+    const steps = [...unknownSteps];
+    const fromTables = new Set(Object.keys(fromSchema.tables));
+    const toTables = new Set(Object.keys(toSchema.tables));
+    for (const table of [...fromTables].filter((name) => !toTables.has(name)).sort()) {
+        steps.push({ kind: 'table.remove', table });
+    }
+    for (const table of [...toTables].filter((name) => !fromTables.has(name)).sort()) {
+        steps.push({ kind: 'table.add', table });
+    }
+    for (const table of [...fromTables].filter((name) => toTables.has(name)).sort()) {
+        steps.push(...tableSteps(table, fromSchema.tables[table], toSchema.tables[table]));
+    }
+    const classification = steps.every(isCompatible) ? 'compatible' : 'incompatible';
+    return { protocol: SCHEMA_PROTOCOL, application, from, to, classification, steps,
+        requiresReset: classification === 'incompatible' };
+}

package/vendor/spec/schema.d.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { type ApplicationManifestV0, type NormalizedApplicationManifestV0 } from './types.js';
+/** The normalized database fragment embedded in artifacts and review metadata. */
+export declare const normalizedDatabaseSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    tables: z.ZodRecord<z.ZodString, z.ZodObject<{
+        fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                datetime: "datetime";
+                bytes: "bytes";
+                json: "json";
+                ref: "ref";
+            }>;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            unique: z.ZodOptional<z.ZodBoolean>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            collate: z.ZodOptional<z.ZodEnum<{
+                binary: "binary";
+                nocase: "nocase";
+                rtrim: "rtrim";
+            }>>;
+            table: z.ZodOptional<z.ZodString>;
+            onDelete: z.ZodOptional<z.ZodEnum<{
+                noAction: "noAction";
+                restrict: "restrict";
+                cascade: "cascade";
+                setNull: "setNull";
+                setDefault: "setDefault";
+            }>>;
+            onUpdate: z.ZodOptional<z.ZodEnum<{
+                noAction: "noAction";
+                restrict: "restrict";
+                cascade: "cascade";
+                setNull: "setNull";
+                setDefault: "setDefault";
+            }>>;
+            generated: z.ZodOptional<z.ZodObject<{
+                expression: z.ZodString;
+                stored: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        indexes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+            columns: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                column: z.ZodString;
+                collate: z.ZodOptional<z.ZodEnum<{
+                    binary: "binary";
+                    nocase: "nocase";
+                    rtrim: "rtrim";
+                }>>;
+                desc: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>, z.ZodObject<{
+                expression: z.ZodString;
+                desc: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>]>>;
+            unique: z.ZodOptional<z.ZodBoolean>;
+            where: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>>;
+        unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        checks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const applicationManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    format: z.ZodLiteral<"xeer.application-source.v0">;
+    name: z.ZodString;
+    entrypoints: z.ZodObject<{
+        client: z.ZodString;
+        server: z.ZodString;
+    }, z.core.$strict>;
+    app: z.ZodOptional<z.ZodObject<{
+        spa: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        favicon: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    database: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodNumber>;
+        tables: z.ZodRecord<z.ZodString, z.ZodObject<{
+            fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    string: "string";
+                    number: "number";
+                    boolean: "boolean";
+                    datetime: "datetime";
+                    bytes: "bytes";
+                    json: "json";
+                    ref: "ref";
+                }>;
+                optional: z.ZodOptional<z.ZodBoolean>;
+                maxLength: z.ZodOptional<z.ZodNumber>;
+                unique: z.ZodOptional<z.ZodBoolean>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                collate: z.ZodOptional<z.ZodEnum<{
+                    binary: "binary";
+                    nocase: "nocase";
+                    rtrim: "rtrim";
+                }>>;
+                table: z.ZodOptional<z.ZodString>;
+                onDelete: z.ZodOptional<z.ZodEnum<{
+                    noAction: "noAction";
+                    restrict: "restrict";
+                    cascade: "cascade";
+                    setNull: "setNull";
+                    setDefault: "setDefault";
+                }>>;
+                onUpdate: z.ZodOptional<z.ZodEnum<{
+                    noAction: "noAction";
+                    restrict: "restrict";
+                    cascade: "cascade";
+                    setNull: "setNull";
+                    setDefault: "setDefault";
+                }>>;
+                generated: z.ZodOptional<z.ZodObject<{
+                    expression: z.ZodString;
+                    stored: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            indexes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+                columns: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    column: z.ZodString;
+                    collate: z.ZodOptional<z.ZodEnum<{
+                        binary: "binary";
+                        nocase: "nocase";
+                        rtrim: "rtrim";
+                    }>>;
+                    desc: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>, z.ZodObject<{
+                    expression: z.ZodString;
+                    desc: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>]>>;
+                unique: z.ZodOptional<z.ZodBoolean>;
+                where: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+            checks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    storage: z.ZodOptional<z.ZodObject<{
+        maxObjectBytes: z.ZodOptional<z.ZodNumber>;
+        readBytes: z.ZodOptional<z.ZodNumber>;
+        writeBytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        database: "database";
+        storage: "storage";
+    }>>>;
+    budgets: z.ZodOptional<z.ZodObject<{
+        queryRows: z.ZodOptional<z.ZodNumber>;
+        mutationWrites: z.ZodOptional<z.ZodNumber>;
+        requestBytes: z.ZodOptional<z.ZodNumber>;
+        responseBytes: z.ZodOptional<z.ZodNumber>;
+        liveConnections: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Stable editor-facing schema location emitted into every scaffolded `xeer.app.json`. */
+export declare const APPLICATION_MANIFEST_SCHEMA_URL: "https://docs.xeer.run/application-v0.schema.json";
+export declare const applicationManifestJsonSchema: Readonly<Record<string, unknown>>;
+export declare function parseApplicationManifest(value: unknown): ApplicationManifestV0;
+export declare function normalizeApplicationManifest(manifest: ApplicationManifestV0): NormalizedApplicationManifestV0;