@impetik/xeer-mcp 0.2.5 → 0.2.7

package/vendor/spec/types.d.ts

@@ -0,0 +1,275 @@
+import type { PublicAssetsV0 } from './public-assets.js';
+export declare const SOURCE_FORMAT: "xeer.application-source.v0";
+export declare const ARTIFACT_FORMAT: "xeer.application.v0";
+export declare const DEV_PROTOCOL: "xeer.dev.v0";
+export declare const INSPECT_PROTOCOL: "xeer.inspect.v0";
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+export interface SourceSpan {
+    line: number;
+    column: number;
+    length?: number;
+}
+export interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    file?: string;
+    span?: SourceSpan;
+    hint?: string;
+}
+/**
+ * `ref` is a scalar in the only sense that matters here: it is one TEXT column holding one row id.
+ * What distinguishes it is that the column carries a FOREIGN KEY to the declared table it names, so
+ * the database — not the application — is what keeps the pointer honest.
+ */
+export type ScalarType = 'string' | 'number' | 'boolean' | 'datetime' | 'bytes' | 'json' | 'ref';
+/** SQLite's three built-in collating sequences; there are no others to declare. */
+export type CollationName = 'binary' | 'nocase' | 'rtrim';
+/** SQLite's five referential actions, spelled the way the rest of the manifest spells things. */
+export type ReferentialAction = 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
+/**
+ * A field's default, in the JavaScript type its field type is written in: a `boolean` field defaults
+ * to `true`, a `number` to a number, and every text-shaped type to a string. A `bytes` default is
+ * lowercase hex, which is the only unambiguous way to spell a byte sequence in JSON.
+ */
+export type FieldDefaultValue = string | number | boolean;
+export interface GeneratedColumnDefinition {
+    /** A SQL expression over this table's other columns. See `sql-expression.ts` for what may appear. */
+    expression: string;
+    /** `true` writes the value to disk; the default recomputes it on read. */
+    stored?: boolean;
+}
+export interface FieldDefinition {
+    type: ScalarType;
+    optional?: boolean;
+    maxLength?: number;
+    /** A single-column UNIQUE. Optional columns may still repeat NULL, as SQL defines UNIQUE. */
+    unique?: boolean;
+    /** Permitted values for a string field, enforced as a membership CHECK. */
+    enum?: string[];
+    default?: FieldDefaultValue;
+    collate?: CollationName;
+    /** `ref` only: the declared table whose `id` this column points at. */
+    table?: string;
+    /** `ref` only. Absent means SQLite's default, NO ACTION. */
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
+    /** Makes the column computed. A generated column may not also carry a default. */
+    generated?: GeneratedColumnDefinition;
+}
+/** One member of an index: a column, a column with options, or an expression to index. */
+export type IndexTermDefinition = string | {
+    column: string;
+    collate?: CollationName;
+    desc?: boolean;
+} | {
+    expression: string;
+    desc?: boolean;
+};
+export interface IndexDefinition {
+    columns: IndexTermDefinition[];
+    unique?: boolean;
+    /**
+     * A partial index's predicate: the index then covers only the rows it matches.
+     *
+     * Note for anything that writes through one: an upsert targeting a *unique* partial index has to
+     * repeat the predicate — `ON CONFLICT ("slug") WHERE "deletedAt" IS NULL DO UPDATE …` — or SQLite
+     * answers "ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint". The predicate
+     * is part of the constraint's identity, not a detail of it.
+     */
+    where?: string;
+}
+/**
+ * An index is either a bare list of column names or the full form. The shorthand is not legacy: an
+ * index over two ascending columns is most of them, and `["status", "position"]` says that better
+ * than the object it normalizes to.
+ */
+export type TableIndexDefinition = string[] | IndexDefinition;
+export interface TableDefinition {
+    fields: Record<string, FieldDefinition>;
+    indexes?: Record<string, TableIndexDefinition>;
+    /** Composite UNIQUE constraints, each a tuple of declared field names. */
+    unique?: string[][];
+    /** Table-level CHECK expressions by name. The name is what SQLite reports when one fails. */
+    checks?: Record<string, string>;
+}
+/**
+ * The capabilities an application may declare. A capability name in `capabilities[]` and its config
+ * block are one declaration in two halves: either both are present or neither is, checked in both
+ * directions by the schema. `database` has worked this way since v0; `storage` is the first
+ * Cloudflare-primitive-backed capability to follow it (#29, design in #51).
+ */
+export declare const CAPABILITIES: readonly ["database", "storage"];
+export type Capability = (typeof CAPABILITIES)[number];
+/**
+ * The `storage` capability's declared limits. Every field is optional and normalized to a default,
+ * and every one is a *logical* limit — a byte count the runtime enforces at call time. Nothing here
+ * names a bucket, a region, or an account: the provisioned resource's identity is deployment state
+ * owned by the control plane and is deliberately absent from the manifest and the artifact (#51 §7).
+ */
+export interface StorageConfigV0 {
+    /** Largest single stored object, capped at `STORAGE_MAX_OBJECT_BYTES`. */
+    maxObjectBytes?: number;
+    /** Bytes one handler may read out of storage, capped at `STORAGE_MAX_READ_BYTES`. */
+    readBytes?: number;
+    /** Bytes one handler may write into storage, capped at `STORAGE_MAX_WRITE_BYTES`. */
+    writeBytes?: number;
+}
+export interface NormalizedStorageConfigV0 {
+    maxObjectBytes: number;
+    readBytes: number;
+    writeBytes: number;
+}
+export interface ApplicationManifestV0 {
+    $schema?: string;
+    format: typeof SOURCE_FORMAT;
+    name: string;
+    entrypoints: {
+        client: string;
+        server: string;
+    };
+    app?: {
+        spa?: boolean;
+        title?: string;
+        language?: string;
+        description?: string;
+        favicon?: string;
+    };
+    database?: {
+        version?: number;
+        tables: Record<string, TableDefinition>;
+    };
+    storage?: StorageConfigV0;
+    capabilities?: Capability[];
+    budgets?: {
+        queryRows?: number;
+        mutationWrites?: number;
+        requestBytes?: number;
+        responseBytes?: number;
+        /**
+         * Simultaneous server-push invalidation streams the application's state object will hold.
+         * `0` disables server push for the application: the client never opens `/__xeer/events` and the
+         * runtime answers a terminal `live_disabled` without waking the state object.
+         */
+        liveConnections?: number;
+    };
+}
+export interface NormalizedApplicationManifestV0 {
+    format: typeof SOURCE_FORMAT;
+    name: string;
+    entrypoints: ApplicationManifestV0['entrypoints'];
+    app: {
+        spa: boolean;
+        title: string;
+        language: string;
+        description: string;
+        favicon: string | null;
+    };
+    database: {
+        version: number;
+        tables: Record<string, TableDefinition>;
+    };
+    /**
+     * The normalized `storage` block, or `null` when the capability is not declared. Null rather than a
+     * zeroed record, because "this application has no storage" and "this application has storage with
+     * a limit of nothing" are different statements and only the first one is ever true.
+     */
+    storage: NormalizedStorageConfigV0 | null;
+    capabilities: Capability[];
+    budgets: {
+        queryRows: number;
+        mutationWrites: number;
+        requestBytes: number;
+        responseBytes: number;
+        /** `0` means server push is off for this application; see {@link ApplicationManifestV0}. */
+        liveConnections: number;
+    };
+}
+export interface SourceReceipt {
+    path: string;
+    size: number;
+    hash: `sha256:${string}`;
+}
+export interface ApplicationSchemaIdentityV0 {
+    applicationSchemaVersion: number;
+    schemaHash: `sha256:${string}`;
+}
+export interface ApplicationArtifactV0 {
+    format: typeof ARTIFACT_FORMAT;
+    artifactId: `sha256:${string}`;
+    compiler: {
+        name: '@impetik/xeer';
+        version: string;
+    };
+    application: {
+        name: string;
+        sourceFormat: typeof SOURCE_FORMAT;
+        app: NormalizedApplicationManifestV0['app'];
+    };
+    runtime: {
+        family: 'workerd';
+        compatibilityDate: string;
+        compatibilityFlags: string[];
+    };
+    capabilities: NormalizedApplicationManifestV0['capabilities'];
+    /**
+     * The normalized `storage` limits, present only when the capability is declared.
+     *
+     * Present-only-when-declared rather than `storage: null`, so an application that does not use the
+     * capability produces byte-identical artifact bytes — and therefore the same `artifactId` — as it
+     * did before the capability existed. What is deliberately *not* here is the provisioned bucket's
+     * name: it is derived from `(appId, environment)` by the control plane at deploy time, so the same
+     * artifact binds different buckets in preview and production, which is correct (#51 §7).
+     */
+    storage?: NormalizedStorageConfigV0;
+    budgets: NormalizedApplicationManifestV0['budgets'];
+    schema: NormalizedApplicationManifestV0['database'];
+    schemaIdentity: ApplicationSchemaIdentityV0;
+    operations: {
+        queries: Array<{
+            name: string;
+        }>;
+        mutations: Array<{
+            name: string;
+        }>;
+        endpoints: Array<{
+            method: string;
+            path: string;
+        }>;
+    };
+    modules: Array<{
+        path: string;
+        size: number;
+        hash: `sha256:${string}`;
+        sourceMap?: {
+            format: 'source-map.v3';
+            size: number;
+            hash: `sha256:${string}`;
+        };
+    }>;
+    assets: Array<{
+        path: string;
+        contentType: string;
+        size: number;
+        hash: `sha256:${string}`;
+    }>;
+    /**
+     * Which of the paths in `assets` are content addresses and which are stable contracts — the only
+     * sanctioned basis for deciding what may be cached and for how long. It is part of the artifact
+     * rather than something the CLI derives at deploy time because the document is generated
+     * downstream by a CLI whose version is not pinned to this build: two CLI versions hashing
+     * independently could name different URLs for identical bytes, and the hashed URL has to be a
+     * property of the bytes alone. Being here also makes it covered by `artifactId`.
+     */
+    publicAssets: PublicAssetsV0;
+    source: {
+        files: SourceReceipt[];
+    };
+}
+export interface DevEvent<T = unknown> {
+    protocol: typeof DEV_PROTOCOL;
+    seq: number;
+    time: string;
+    type: string;
+    data: T;
+}

package/vendor/spec/types.js

@@ -0,0 +1,11 @@
+export const SOURCE_FORMAT = 'xeer.application-source.v0';
+export const ARTIFACT_FORMAT = 'xeer.application.v0';
+export const DEV_PROTOCOL = 'xeer.dev.v0';
+export const INSPECT_PROTOCOL = 'xeer.inspect.v0';
+/**
+ * The capabilities an application may declare. A capability name in `capabilities[]` and its config
+ * block are one declaration in two halves: either both are present or neither is, checked in both
+ * directions by the schema. `database` has worked this way since v0; `storage` is the first
+ * Cloudflare-primitive-backed capability to follow it (#29, design in #51).
+ */
+export const CAPABILITIES = Object.freeze(['database', 'storage']);

package/vendor/spec/value.d.ts

@@ -0,0 +1,22 @@
+export type RuntimeValue = null | boolean | number | string | Date | Uint8Array | undefined | RuntimeValue[] | {
+    [key: string]: RuntimeValue;
+};
+export type EncodedValue = null | boolean | number | string | {
+    $xeer: 'undefined';
+} | {
+    $xeer: 'date';
+    value: string;
+} | {
+    $xeer: 'bytes';
+    value: string;
+} | {
+    $xeer: 'array';
+    value: EncodedValue[];
+} | {
+    $xeer: 'object';
+    value: Record<string, EncodedValue>;
+};
+export declare function encodeValue(value: RuntimeValue): EncodedValue;
+export declare function decodeValue(value: EncodedValue): RuntimeValue;
+export declare function stringifyValue(value: RuntimeValue): string;
+export declare function parseValue(value: string): RuntimeValue;

package/vendor/spec/value.js

@@ -0,0 +1,72 @@
+function bytesToBase64(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + chunk));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+export function encodeValue(value) {
+    const ancestors = new Set();
+    const encode = (current) => {
+        if (current === null || typeof current === 'string' || typeof current === 'boolean')
+            return current;
+        if (typeof current === 'number') {
+            if (!Number.isFinite(current))
+                throw new TypeError('Xeer values cannot contain non-finite numbers.');
+            return Object.is(current, -0) ? 0 : current;
+        }
+        if (current === undefined)
+            return { $xeer: 'undefined' };
+        if (current instanceof Date) {
+            if (Number.isNaN(current.getTime()))
+                throw new TypeError('Xeer values cannot contain an invalid Date.');
+            return { $xeer: 'date', value: current.toISOString() };
+        }
+        if (current instanceof Uint8Array)
+            return { $xeer: 'bytes', value: bytesToBase64(current) };
+        if (ancestors.has(current))
+            throw new TypeError('Xeer values cannot contain cycles.');
+        ancestors.add(current);
+        try {
+            if (Array.isArray(current))
+                return { $xeer: 'array', value: current.map(encode) };
+            const prototype = Object.getPrototypeOf(current);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new TypeError('Xeer values only support plain objects.');
+            }
+            const encoded = {};
+            for (const key of Object.keys(current).sort())
+                encoded[key] = encode(current[key]);
+            return { $xeer: 'object', value: encoded };
+        }
+        finally {
+            ancestors.delete(current);
+        }
+    };
+    return encode(value);
+}
+export function decodeValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
+        return value;
+    switch (value.$xeer) {
+        case 'undefined': return undefined;
+        case 'date': return new Date(value.value);
+        case 'bytes': return base64ToBytes(value.value);
+        case 'array': return value.value.map(decodeValue);
+        case 'object': return Object.fromEntries(Object.entries(value.value).map(([key, item]) => [key, decodeValue(item)]));
+    }
+}
+export function stringifyValue(value) {
+    return JSON.stringify(encodeValue(value));
+}
+export function parseValue(value) {
+    return decodeValue(JSON.parse(value));
+}