@impetik/xeer-mcp 0.2.16 → 0.2.18

package/vendor/spec/type-check-profile.js

@@ -0,0 +1,78 @@
+/**
+ * The platform TypeScript profile, in the spelling a `tsconfig.json` uses.
+ *
+ * `xeer check` type-checks an application with its own compiler options rather than the project's
+ * `tsconfig.json`, because the answer must not depend on a file the author can edit. The editor,
+ * however, reads only the `tsconfig.json` — so anything the platform enforces and the scaffold omits
+ * shows up as a green editor and a red CLI, which is what `exactOptionalPropertyTypes` did (#248).
+ *
+ * The repair is not to copy the flags into the scaffold: a copy is a thing that drifts. This module
+ * is the one declaration. The compiler converts it into `ts.CompilerOptions` for the check, and the
+ * scaffold writes it into `tsconfig.json` verbatim, so the two cannot disagree without this file
+ * changing. It lives in the spec package rather than the compiler so that writing a scaffold does
+ * not require loading TypeScript.
+ *
+ * Values are the JSON spellings TypeScript accepts in a `tsconfig.json` (`"esnext"`, `"bundler"`,
+ * `"react-jsx"`, `lib` without the `lib.`/`.d.ts` affixes), which is what
+ * `ts.convertCompilerOptionsFromJson` reads.
+ */
+export const PLATFORM_TYPE_CHECK_COMPILER_OPTIONS = Object.freeze({
+    allowJs: true,
+    allowArbitraryExtensions: true,
+    checkJs: true,
+    exactOptionalPropertyTypes: true,
+    jsx: 'react-jsx',
+    jsxImportSource: '@impetik/xeer',
+    lib: Object.freeze(['es2022', 'dom', 'dom.iterable']),
+    module: 'esnext',
+    moduleResolution: 'bundler',
+    noEmit: true,
+    noUncheckedIndexedAccess: true,
+    skipLibCheck: true,
+    strict: true,
+    target: 'es2022',
+    types: Object.freeze([]),
+    verbatimModuleSyntax: true,
+});
+/**
+ * The React-family editor mappings every scaffolded and template `tsconfig.json` carries. Each
+ * target is a shim inside the installed platform package that re-exports the platform's
+ * `preact/compat` surface, so the mapping resolves under npm hoisting and pnpm strictness alike.
+ *
+ * Not part of {@link PLATFORM_TYPE_CHECK_COMPILER_OPTIONS}: the platform check answers the same
+ * question through its module-resolution host instead, so this is the editor's half of one rule
+ * rather than a second rule.
+ */
+export const REACT_COMPAT_TSCONFIG_PATHS = Object.freeze({
+    'react': ['./node_modules/@impetik/xeer/dist/compat/react'],
+    'react-dom': ['./node_modules/@impetik/xeer/dist/compat/react-dom'],
+    'react-dom/client': ['./node_modules/@impetik/xeer/dist/compat/react-dom-client'],
+    'react/jsx-runtime': ['./node_modules/@impetik/xeer/dist/compat/react-jsx-runtime'],
+    'react/jsx-dev-runtime': ['./node_modules/@impetik/xeer/dist/compat/react-jsx-dev-runtime'],
+});
+/**
+ * The files an application's `tsconfig.json` type-checks: sources, TypeScript tests, and the
+ * generated contract.
+ *
+ * `tests/**\/*.ts` rather than `tests`, because the profile enables `checkJs` and the two sides build
+ * their file sets differently. The platform checks the entrypoint graph plus `tests/**\/*.test.ts`,
+ * so a `.js` file it reaches is a file it judges; a tsconfig's set is a directory glob, and `tests`
+ * would additionally drag in a `.mjs` harness written for Node — a file neither side is judging the
+ * same way. Restricting the glob to TypeScript keeps the two sets comparable without weakening any
+ * rule that decides how a checked file is judged.
+ */
+export const APPLICATION_TSCONFIG_INCLUDE = Object.freeze(['src', 'tests/**/*.ts', '.xeer/generated/**/*.d.ts']);
+/**
+ * The `tsconfig.json` document an application carries, as a serialized file body.
+ *
+ * One function so the scaffold, the checked-in templates, and any conformance test all name the same
+ * bytes. Serialized here rather than returned as an object because "the file the editor reads" is
+ * what has to match, and two callers stringifying the same object with different options would
+ * produce two different files.
+ */
+export function applicationTsconfigDocument() {
+    return `${JSON.stringify({
+        compilerOptions: { ...PLATFORM_TYPE_CHECK_COMPILER_OPTIONS, paths: REACT_COMPAT_TSCONFIG_PATHS },
+        include: APPLICATION_TSCONFIG_INCLUDE,
+    }, null, 2)}\n`;
+}

package/vendor/spec/types.d.ts

@@ -16,6 +16,20 @@ export interface Diagnostic {
     file?: string;
     span?: SourceSpan;
     hint?: string;
+    /**
+     * Set on a diagnostic that invalidated the generated contract: the compiler could not describe the
+     * application's operations, so every type derived from them is wrong downstream. Absent means
+     * "nothing is known", not "not primary" — a consumer that ignores the field reads the envelope
+     * exactly as it did before the field existed.
+     */
+    primary?: true;
+    /**
+     * The `code` of the contract-invalidating diagnostic this one is a consequence of. Present only
+     * when the causal link is structural — the file consumes the contract the primary diagnostic
+     * broke — and never on a diagnostic in a file that carries a primary. Repair the primaries and
+     * re-run: a `causedBy` diagnostic that survives is a real error carrying its own location.
+     */
+    causedBy?: string;
 }
 /**
  * `ref` is a scalar in the only sense that matters here: it is one TEXT column holding one row id.
@@ -92,6 +106,22 @@ export interface TableDefinition {
     unique?: string[][];
     /** Table-level CHECK expressions by name. The name is what SQLite reports when one fails. */
     checks?: Record<string, string>;
+    /**
+     * Who chooses a row's `id`. Defaults to `"runtime"`, which mints an unguessable uuid and refuses
+     * an `id` on insert.
+     *
+     * `"application"` makes `insert({ id, … })` required for this table and this table only, so a row
+     * can *be* the thing an outside system already names — the case this exists for is a `workspaces`
+     * row whose id is the identity provider's workspace id, which makes `ref` and
+     * `workspaceTable({ workspaceField: 'id' })` work against it without a second column to join
+     * through (decision 0006).
+     *
+     * Opt-in per table so the default stays the safe one: an application that does not ask for this
+     * cannot accidentally accept a client-chosen id. Nothing about the column changes — `id` is
+     * `TEXT PRIMARY KEY` either way — so a collision is the primary key's own constraint rather than
+     * new machinery, and turning this on or off is physically compatible with the rows already stored.
+     */
+    idSource?: 'runtime' | 'application';
 }
 /**
  * The capabilities an application may declare. A capability name in `capabilities[]` and its config
@@ -101,6 +131,16 @@ export interface TableDefinition {
  */
 export declare const CAPABILITIES: readonly ["database", "storage"];
 export type Capability = (typeof CAPABILITIES)[number];
+/**
+ * Bytes one streamed endpoint response may pump when `budgets.streamedBytes` is not declared.
+ *
+ * Applied where the budget is *read* rather than where the manifest is normalized, because
+ * normalized budgets go into the artifact payload verbatim: materializing this default would move
+ * the `artifactId` of every application that never asked for a streamed response. It matches the
+ * `responseBytes` default so that turning an endpoint from buffered to streamed does not silently
+ * change how many bytes it may send.
+ */
+export declare const STREAMED_BYTES_DEFAULT = 1048576;
 /**
  * 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
@@ -141,6 +181,18 @@ export interface ApplicationManifestV0 {
     };
     storage?: StorageConfigV0;
     capabilities?: Capability[];
+    /**
+     * The client runtime selection (#212). Optional, and closed: only implemented provider/source
+     * combinations are accepted, and omission normalizes to `{ provider: "preact", source:
+     * "platform" }` with identical semantics and build output. Declaring it is a statement of the
+     * default, not a choice — a future app-owned source would be `"application"`, not `"user"`.
+     */
+    client?: {
+        runtime?: {
+            provider: 'preact';
+            source?: 'platform';
+        };
+    };
     budgets?: {
         queryRows?: number;
         mutationWrites?: number;
@@ -152,6 +204,21 @@ export interface ApplicationManifestV0 {
          * runtime answers a terminal `live_disabled` without waking the state object.
          */
         liveConnections?: number;
+        /**
+         * Bytes one streamed endpoint response may pump through the platform.
+         *
+         * A streamed body is bounded, not exempt: `responseBytes` bounds a body the platform buffered and
+         * can still refuse as a whole, and this bounds one the platform has already begun sending and can
+         * only terminate. They are different failures, so they are different ceilings. Exceeding this one
+         * aborts the stream mid-body, which the client observes as a failed read rather than a refusal.
+         */
+        streamedBytes?: number;
+        /**
+         * Error-tier byte budget for the minified pre-gzip client JavaScript bundle. Defaults to the
+         * platform's 1 MiB when omitted; bounded above by the 10 MiB module ceiling. The advisory tier
+         * is fixed and not declarable.
+         */
+        clientBundleBytes?: number;
     };
 }
 export interface NormalizedApplicationManifestV0 {
@@ -176,13 +243,40 @@ export interface NormalizedApplicationManifestV0 {
      */
     storage: NormalizedStorageConfigV0 | null;
     capabilities: Capability[];
+    /** Always present once normalized: omission and the explicit default are the same statement. */
+    client: {
+        runtime: {
+            provider: 'preact';
+            source: 'platform';
+        };
+    };
     budgets: {
         queryRows: number;
         mutationWrites: number;
         requestBytes: number;
         responseBytes: number;
-        /** `0` means server push is off for this application; see {@link ApplicationManifestV0}. */
+        /**
+         * `0` means server push is off for this application; see {@link ApplicationManifestV0}.
+         *
+         * It is the ceiling on **every** server→client byte channel the state object holds open, not on
+         * live invalidation alone: an SSE subscription and a streamed endpoint response occupy the same
+         * pool. Two separately-bounded pools would add up to an unbounded total, which is the one answer
+         * decision 0007 refused.
+         */
         liveConnections: number;
+        /**
+         * Bytes one streamed endpoint response may pump; see {@link ApplicationManifestV0}.
+         *
+         * Present only when the manifest declares it, mirroring `clientBundleBytes` below: an
+         * application on the platform default hashes exactly as it did before the budget existed.
+         * Read it as `streamedBytes ?? STREAMED_BYTES_DEFAULT`.
+         */
+        streamedBytes?: number;
+        /**
+         * Present only when the manifest declares it, mirroring `storage`: an application on the
+         * platform default hashes exactly as it did before the budget was declarable.
+         */
+        clientBundleBytes?: number;
     };
 }
 export interface SourceReceipt {
@@ -190,6 +284,36 @@ export interface SourceReceipt {
     size: number;
     hash: `sha256:${string}`;
 }
+/**
+ * Provenance for one npm package a zone bundle consumed (#212, #244). `files` receipts the exact
+ * bytes the bundler read — strictly stronger than lockfile integrity, which pins tarballs rather
+ * than the post-install state a patch or postinstall script left on disk.
+ *
+ * Deliberately not keyed by zone. A package both bundles consume is one dependency of one
+ * application at one version, and receipting it twice would say the artifact used two. The receipt
+ * is the union of the files either bundle read, so the same package contributing different modules
+ * to each zone is still one entry covering every byte that entered the artifact.
+ */
+export interface BundledDependencyReceiptV0 {
+    name: string;
+    version: string;
+    /** The metafile inputs consumed from this package, package-root-relative, content-hashed. */
+    files: SourceReceipt[];
+}
+/**
+ * The application-dependency provenance block, present in an artifact only when the bundle
+ * consumed open dependencies. The lockfile identity is opportunistic — recorded when a parseable
+ * npm or pnpm lockfile is found — and never an admission gate: workspace applications have no
+ * per-app lockfile at all.
+ */
+export interface BundledDependenciesV0 {
+    packages: BundledDependencyReceiptV0[];
+    lockfile?: {
+        manager: 'npm' | 'pnpm';
+        path: string;
+        hash: `sha256:${string}`;
+    };
+}
 export interface ApplicationSchemaIdentityV0 {
     applicationSchemaVersion: number;
     schemaHash: `sha256:${string}`;
@@ -222,6 +346,13 @@ export interface ApplicationArtifactV0 {
      * artifact binds different buckets in preview and production, which is correct (#51 §7).
      */
     storage?: NormalizedStorageConfigV0;
+    /**
+     * The normalized client runtime, recorded when the application declares `client` or the *client*
+     * bundle consumed open dependencies. Present-only-then for the same reason as `storage`: an
+     * untouched application keeps its `artifactId` (#212). A server-only dependency does not record
+     * it — nothing about the renderer was chosen by importing one (#244).
+     */
+    clientRuntime?: NormalizedApplicationManifestV0['client']['runtime'];
     budgets: NormalizedApplicationManifestV0['budgets'];
     schema: NormalizedApplicationManifestV0['database'];
     schemaIdentity: ApplicationSchemaIdentityV0;
@@ -264,6 +395,8 @@ export interface ApplicationArtifactV0 {
     publicAssets: PublicAssetsV0;
     source: {
         files: SourceReceipt[];
+        /** Present only when the client bundle consumed open application dependencies (#212). */
+        dependencies?: BundledDependenciesV0;
     };
 }
 export interface DevEvent<T = unknown> {

package/vendor/spec/types.js

@@ -9,3 +9,13 @@ export const INSPECT_PROTOCOL = 'xeer.inspect.v0';
  * Cloudflare-primitive-backed capability to follow it (#29, design in #51).
  */
 export const CAPABILITIES = Object.freeze(['database', 'storage']);
+/**
+ * Bytes one streamed endpoint response may pump when `budgets.streamedBytes` is not declared.
+ *
+ * Applied where the budget is *read* rather than where the manifest is normalized, because
+ * normalized budgets go into the artifact payload verbatim: materializing this default would move
+ * the `artifactId` of every application that never asked for a streamed response. It matches the
+ * `responseBytes` default so that turning an endpoint from buffered to streamed does not silently
+ * change how many bytes it may send.
+ */
+export const STREAMED_BYTES_DEFAULT = 1_048_576;