@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/admin-sql.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How a single SQL statement may be run against an application's own database.
+ *
+ * The shape of this is not obvious, so the reasoning is here rather than in a commit message.
+ *
+ * Direct SQL is safer than it looks. The schema's `CHECK`, `NOT NULL`, `UNIQUE` and foreign-key
+ * constraints bind *every* writer, not only `ctx.db` — `UPDATE posts SET position = 'abc'` is refused
+ * by the same constraint that makes the column numeric in the first place, because SQLite's NUMERIC
+ * is an affinity and the CHECK is the actual contract. Ordinary DML therefore cannot store a value
+ * the generated types call impossible.
+ *
+ * Two things escape that, and they are what this refuses.
+ *
+ * `PRAGMA ignore_check_constraints` is writable and genuinely switches `CHECK` off. A console that
+ * could set it would write exactly the values the contract forbids, and the application would then
+ * read them back through an interface whose types say they cannot exist.
+ *
+ * DDL is worse, and it is why writes are gated rather than simply allowed. The runtime reconciles the
+ * physical schema against the DDL text it recorded, so a `DROP TABLE` from a console desynchronises
+ * bookkeeping the runtime believes it owns alone. That is not an operator changing their own data,
+ * which is their business — it is a failure that surfaces later and looks like a runtime bug.
+ *
+ * So: reads by default, writes only when asked for explicitly, and neither DDL nor a pragma that can
+ * change enforcement at all.
+ */
+import type { EncodedValue } from './value.js';
+import { ADMIN_PROTOCOL } from './admin.js';
+export type AdminStatementKind = 'read' | 'write';
+export type AdminStatementRefusalCode = 'admin_sql_empty' | 'admin_sql_multiple_statements' | 'admin_sql_statement_not_allowed' | 'admin_sql_pragma_not_allowed' | 'admin_sql_reserved_table';
+export interface AdminStatementRefusal {
+    readonly code: AdminStatementRefusalCode;
+    readonly message: string;
+}
+export type AdminStatementClassification = {
+    readonly ok: true;
+    readonly kind: AdminStatementKind;
+} | {
+    readonly ok: false;
+    readonly refusal: AdminStatementRefusal;
+};
+/**
+ * Decides whether one statement may run, and whether it counts as a write.
+ *
+ * `reservedTable` is injected rather than imported so this stays a pure decision about SQL text; the
+ * runtime passes the same reservation the schema generator uses.
+ */
+export declare function classifyAdminStatement(sql: string, reservedTable: (name: string) => boolean): AdminStatementClassification;
+/** The most rows one statement returns before the rest are withheld and `truncated` is reported. */
+export declare const ADMIN_SQL_MAX_ROWS = 200;
+export interface AdminSqlResponseV0 {
+    protocol: typeof ADMIN_PROTOCOL;
+    /** Column names in result order, so a caller can render a table without inspecting every row. */
+    columns: readonly string[];
+    rows: readonly EncodedValue[];
+    /** Rows changed by a write. Absent for a read. */
+    rowsWritten?: number;
+    /** True when the statement produced more rows than {@link ADMIN_SQL_MAX_ROWS}. */
+    truncated: boolean;
+}

package/vendor/spec/admin-sql.js

@@ -0,0 +1,147 @@
+/**
+ * How a single SQL statement may be run against an application's own database.
+ *
+ * The shape of this is not obvious, so the reasoning is here rather than in a commit message.
+ *
+ * Direct SQL is safer than it looks. The schema's `CHECK`, `NOT NULL`, `UNIQUE` and foreign-key
+ * constraints bind *every* writer, not only `ctx.db` — `UPDATE posts SET position = 'abc'` is refused
+ * by the same constraint that makes the column numeric in the first place, because SQLite's NUMERIC
+ * is an affinity and the CHECK is the actual contract. Ordinary DML therefore cannot store a value
+ * the generated types call impossible.
+ *
+ * Two things escape that, and they are what this refuses.
+ *
+ * `PRAGMA ignore_check_constraints` is writable and genuinely switches `CHECK` off. A console that
+ * could set it would write exactly the values the contract forbids, and the application would then
+ * read them back through an interface whose types say they cannot exist.
+ *
+ * DDL is worse, and it is why writes are gated rather than simply allowed. The runtime reconciles the
+ * physical schema against the DDL text it recorded, so a `DROP TABLE` from a console desynchronises
+ * bookkeeping the runtime believes it owns alone. That is not an operator changing their own data,
+ * which is their business — it is a failure that surfaces later and looks like a runtime bug.
+ *
+ * So: reads by default, writes only when asked for explicitly, and neither DDL nor a pragma that can
+ * change enforcement at all.
+ */
+import { ADMIN_PROTOCOL } from './admin.js';
+/** Statements that only read. `EXPLAIN` is here because it plans a statement without running it. */
+const READ_VERBS = new Set(['SELECT', 'WITH', 'VALUES', 'EXPLAIN']);
+const WRITE_VERBS = new Set(['INSERT', 'UPDATE', 'DELETE', 'REPLACE']);
+/**
+ * Pragmas that only report. An allowlist rather than a denylist, because the case that must never
+ * slip through is precisely the one nobody remembered to add to a pattern.
+ */
+const READ_PRAGMAS = new Set([
+    'table_info', 'table_xinfo', 'table_list', 'index_list', 'index_info', 'index_xinfo',
+    'foreign_key_list', 'foreign_key_check', 'quick_check',
+]);
+/**
+ * Walks the statement, skipping anything that is not code, and reports its leading keyword and
+ * whether a second statement follows.
+ *
+ * The walk exists for one reason: a `;` inside a string literal or a comment is not a separator. A
+ * rule written as a substring search would either refuse `WHERE note = 'a;b'` or accept
+ * `SELECT 1; DROP TABLE posts`, and both are wrong in the direction that matters.
+ */
+function scanStatement(sql) {
+    const words = [];
+    let index = 0;
+    let terminated = false;
+    while (index < sql.length) {
+        const char = sql[index];
+        if (char === '-' && sql[index + 1] === '-') {
+            const end = sql.indexOf('\n', index);
+            index = end < 0 ? sql.length : end + 1;
+            continue;
+        }
+        if (char === '/' && sql[index + 1] === '*') {
+            const end = sql.indexOf('*/', index + 2);
+            index = end < 0 ? sql.length : end + 2;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`' || char === '[') {
+            const closing = char === '[' ? ']' : char;
+            let end = index + 1;
+            while (end < sql.length && sql[end] !== closing)
+                end += 1;
+            // A quoted identifier can be a statement's target table, so it counts as a word.
+            if (char !== "'" && words.length < 3)
+                words.push(sql.slice(index + 1, end));
+            index = end + 1;
+            continue;
+        }
+        if (char === ';') {
+            terminated = true;
+            index += 1;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+        // Any code at all after a terminator is a second statement, whatever it happens to be.
+        if (terminated)
+            return { verb: (words[0] ?? '').toUpperCase(), words, multiple: true };
+        if (/[A-Za-z_]/.test(char)) {
+            let end = index;
+            while (end < sql.length && /[A-Za-z0-9_]/.test(sql[end]))
+                end += 1;
+            if (words.length < 3)
+                words.push(sql.slice(index, end));
+            index = end;
+            continue;
+        }
+        index += 1;
+    }
+    return { verb: (words[0] ?? '').toUpperCase(), words, multiple: false };
+}
+/** The table a write targets: the word after `UPDATE`, `INSERT INTO`, `DELETE FROM`, `REPLACE INTO`. */
+function writeTarget(verb, words) {
+    if (verb === 'UPDATE')
+        return words[1] ?? '';
+    // `INSERT`/`REPLACE`/`DELETE` are followed by `INTO`/`FROM`, then the table. `INSERT OR IGNORE`
+    // pushes it further out than the three words scanned, which is why an unrecognized shape returns
+    // nothing and is treated as unnamed rather than as a match.
+    const second = (words[1] ?? '').toUpperCase();
+    return second === 'INTO' || second === 'FROM' ? words[2] ?? '' : '';
+}
+/**
+ * Decides whether one statement may run, and whether it counts as a write.
+ *
+ * `reservedTable` is injected rather than imported so this stays a pure decision about SQL text; the
+ * runtime passes the same reservation the schema generator uses.
+ */
+export function classifyAdminStatement(sql, reservedTable) {
+    const refuse = (code, message) => ({ ok: false, refusal: { code, message } });
+    const { verb, words, multiple } = scanStatement(sql);
+    if (multiple) {
+        return refuse('admin_sql_multiple_statements', 'Send one statement per call. Only the last statement of a batch may carry parameters and only '
+            + 'its rows are returned, so a batch would silently discard results you asked for.');
+    }
+    if (verb === '')
+        return refuse('admin_sql_empty', 'No SQL statement was supplied.');
+    if (verb === 'PRAGMA') {
+        const name = (words[1] ?? '').toLowerCase();
+        if (!READ_PRAGMAS.has(name) || sql.includes('=')) {
+            return refuse('admin_sql_pragma_not_allowed', `PRAGMA ${words[1] ?? '?'} is not available here. Only introspection pragmas run, and none may `
+                + 'be assigned to: one of them switches CHECK enforcement off, which would let this write the '
+                + 'very values the application types say cannot exist.');
+        }
+        return { ok: true, kind: 'read' };
+    }
+    if (READ_VERBS.has(verb))
+        return { ok: true, kind: 'read' };
+    if (WRITE_VERBS.has(verb)) {
+        const target = writeTarget(verb, words);
+        if (target !== '' && reservedTable(target)) {
+            return refuse('admin_sql_reserved_table', `${target} is the runtime's own bookkeeping, not application data. Writing to it desynchronises `
+                + 'the schema the runtime believes it applied from the one that is actually there.');
+        }
+        return { ok: true, kind: 'write' };
+    }
+    return refuse('admin_sql_statement_not_allowed', `${verb} is not available here. Schema changes belong to the manifest: the runtime reconciles the `
+        + 'physical schema against the DDL it recorded, so changing it from outside leaves the two '
+        + 'disagreeing with nothing able to notice.');
+}
+/** The most rows one statement returns before the rest are withheld and `truncated` is reported. */
+export const ADMIN_SQL_MAX_ROWS = 200;

package/vendor/spec/admin.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The admin data protocol: enough of an application's own database, over HTTP, for someone to browse
+ * and edit their rows without the tool doing it being this repository's admin UI.
+ *
+ * It is versioned like `xeer.dev.v0` and `xeer.state-export.v0` because that is the point — the
+ * shapes here are a contract a third party can build against, not the private wire format of one
+ * client. Everything a UI needs to render a table is in `/tables`: field types, constraints, which
+ * columns the runtime owns, and which field a table policy scopes rows by.
+ *
+ * Two decisions are worth stating because they are the ones that would otherwise be reinvented
+ * badly.
+ *
+ * **Paging is keyset, not offset.** A cursor names the last row seen — `(created_at, id)`, which is
+ * a total order because `id` is unique — so a page is a range scan rather than a count-and-skip, and
+ * inserting a row while someone pages does not shift every later page by one. The cursor is opaque
+ * on purpose: it is base64url text and a client should round-trip it, not parse it.
+ *
+ * **The client supplies the row id on create.** That is the whole idempotency story: the insert is
+ * `INSERT OR IGNORE`, so a retried request writes the same id and changes nothing, and the response
+ * says whether this call was the one that created it. No request ledger, no dedupe window.
+ */
+import type { EncodedValue } from './value.js';
+export declare const ADMIN_PROTOCOL: "xeer.admin.v0";
+/** Columns the runtime owns on every table. Present in every row, never writable by a client. */
+export declare const ADMIN_RUNTIME_FIELDS: readonly AdminFieldV0[];
+/** The default and the ceiling for one page. The ceiling bounds the response, not the table. */
+export declare const ADMIN_PAGE_DEFAULT = 50;
+export declare const ADMIN_PAGE_MAX = 200;
+export interface AdminFieldV0 {
+    name: string;
+    type: string;
+    optional: boolean;
+    /** True for a runtime column and for a generated column: both are readable and never writable. */
+    readOnly: boolean;
+    maxLength?: number;
+    enum?: readonly string[];
+    default?: string | number | boolean;
+    collate?: string;
+    unique?: boolean;
+    /** For a `ref` field, the table its value points at. */
+    references?: string;
+    /** For a generated column, the expression that computes it — worth showing, never editable. */
+    generated?: string;
+}
+export interface AdminIndexV0 {
+    name: string;
+    /** Column terms only; an expression term has no name a filter could use. */
+    columns: readonly string[];
+    unique: boolean;
+}
+/**
+ * How a table policy scopes rows, when one is declared.
+ *
+ * Reported because an admin client has to *ask* for the owner or workspace on create: admin access
+ * lifts row visibility but deliberately does not stamp ownership, so a row created without one would
+ * be a row no application user could ever read.
+ */
+export interface AdminTablePolicyV0 {
+    kind: 'owner' | 'workspace';
+    field: string;
+}
+export interface AdminTableV0 {
+    name: string;
+    fields: readonly AdminFieldV0[];
+    indexes: readonly AdminIndexV0[];
+    policy: AdminTablePolicyV0 | null;
+}
+export interface AdminTablesResponseV0 {
+    protocol: typeof ADMIN_PROTOCOL;
+    application: string;
+    artifactId: string;
+    generation: number;
+    schema: {
+        applicationSchemaVersion: number;
+        schemaHash: string;
+    };
+    /** The same three columns on every table, described once rather than repeated per table. */
+    runtimeFields: readonly AdminFieldV0[];
+    tables: readonly AdminTableV0[];
+}
+export interface AdminRowsResponseV0 {
+    protocol: typeof ADMIN_PROTOCOL;
+    table: string;
+    /** Rows in `(created_at, id)` order, each encoded with the `xeer.value.v0` codec. */
+    rows: readonly EncodedValue[];
+    /** Pass back as `?cursor=` for the next page. `null` when this page is the last one. */
+    cursor: string | null;
+}
+export interface AdminWriteResponseV0 {
+    protocol: typeof ADMIN_PROTOCOL;
+    table: string;
+    /** The row after the write, encoded; `null` for a delete. */
+    row: EncodedValue | null;
+    /**
+     * Whether this call was the one that created the row. `false` on a retry of the same id, which is
+     * what makes `POST` safe to repeat.
+     */
+    created?: boolean;
+}
+/**
+ * A page cursor. Opaque to clients by contract, and deliberately not signed: it names a position in
+ * the caller's own data on a surface they already had to authenticate to reach, so there is nothing
+ * for a forged one to disclose that the next page would not have shown anyway.
+ */
+export declare function encodeAdminCursor(createdAt: string, id: string): string;
+/** The inverse, or `null` when the text is not a cursor this version wrote. */
+export declare function decodeAdminCursor(cursor: string): {
+    createdAt: string;
+    id: string;
+} | null;

package/vendor/spec/admin.js

@@ -0,0 +1,58 @@
+/**
+ * The admin data protocol: enough of an application's own database, over HTTP, for someone to browse
+ * and edit their rows without the tool doing it being this repository's admin UI.
+ *
+ * It is versioned like `xeer.dev.v0` and `xeer.state-export.v0` because that is the point — the
+ * shapes here are a contract a third party can build against, not the private wire format of one
+ * client. Everything a UI needs to render a table is in `/tables`: field types, constraints, which
+ * columns the runtime owns, and which field a table policy scopes rows by.
+ *
+ * Two decisions are worth stating because they are the ones that would otherwise be reinvented
+ * badly.
+ *
+ * **Paging is keyset, not offset.** A cursor names the last row seen — `(created_at, id)`, which is
+ * a total order because `id` is unique — so a page is a range scan rather than a count-and-skip, and
+ * inserting a row while someone pages does not shift every later page by one. The cursor is opaque
+ * on purpose: it is base64url text and a client should round-trip it, not parse it.
+ *
+ * **The client supplies the row id on create.** That is the whole idempotency story: the insert is
+ * `INSERT OR IGNORE`, so a retried request writes the same id and changes nothing, and the response
+ * says whether this call was the one that created it. No request ledger, no dedupe window.
+ */
+export const ADMIN_PROTOCOL = 'xeer.admin.v0';
+/** Columns the runtime owns on every table. Present in every row, never writable by a client. */
+export const ADMIN_RUNTIME_FIELDS = Object.freeze([
+    Object.freeze({ name: 'id', type: 'string', optional: false, readOnly: true }),
+    Object.freeze({ name: 'createdAt', type: 'datetime', optional: false, readOnly: true }),
+    Object.freeze({ name: 'updatedAt', type: 'datetime', optional: false, readOnly: true }),
+]);
+/** The default and the ceiling for one page. The ceiling bounds the response, not the table. */
+export const ADMIN_PAGE_DEFAULT = 50;
+export const ADMIN_PAGE_MAX = 200;
+/**
+ * A page cursor. Opaque to clients by contract, and deliberately not signed: it names a position in
+ * the caller's own data on a surface they already had to authenticate to reach, so there is nothing
+ * for a forged one to disclose that the next page would not have shown anyway.
+ */
+export function encodeAdminCursor(createdAt, id) {
+    const text = JSON.stringify([createdAt, id]);
+    return btoa(String.fromCharCode(...new TextEncoder().encode(text)))
+        .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+/** The inverse, or `null` when the text is not a cursor this version wrote. */
+export function decodeAdminCursor(cursor) {
+    try {
+        const padded = cursor.replaceAll('-', '+').replaceAll('_', '/');
+        const bytes = Uint8Array.from(atob(padded + '='.repeat((4 - (padded.length % 4)) % 4)), (c) => c.charCodeAt(0));
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (!Array.isArray(parsed) || parsed.length !== 2)
+            return null;
+        const [createdAt, id] = parsed;
+        if (typeof createdAt !== 'string' || typeof id !== 'string')
+            return null;
+        return { createdAt, id };
+    }
+    catch {
+        return null;
+    }
+}

package/vendor/spec/canonical.d.ts

@@ -0,0 +1,3 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(bytes: string | Uint8Array): `sha256:${string}`;
+export declare function canonicalHash(value: unknown): `sha256:${string}`;

package/vendor/spec/canonical.js

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto';
+function canonicalValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('Canonical JSON cannot encode a non-finite number');
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (typeof value === 'object') {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError('Canonical JSON only accepts plain objects');
+        }
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            if (item === undefined)
+                throw new TypeError(`Canonical JSON cannot encode undefined at ${key}`);
+            result[key] = canonicalValue(item);
+        }
+        return result;
+    }
+    throw new TypeError(`Canonical JSON cannot encode ${typeof value}`);
+}
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+export function sha256(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+export function canonicalHash(value) {
+    return sha256(canonicalJson(value));
+}

package/vendor/spec/diagnostics.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The diagnostic catalogue.
+ *
+ * Xeer's primary user is a coding agent, so a diagnostic code is a stable API:
+ * an agent dispatches on `code`, not on wording. This module is the single
+ * declaration of what each code means and which edit closes it, and the agent
+ * reference shipped with the skill is rendered from it by
+ * `renderDiagnosticsReference()` rather than written by hand.
+ *
+ * `packages/spec/src/diagnostics.test.ts` scans every non-test source file in
+ * the workspace for `XE####` literals and fails when the emitted set and this
+ * catalogue disagree in either direction, so a new code cannot ship
+ * undocumented and a retired code cannot linger here.
+ */
+/** Where an agent observes a code, in the vocabulary of the CLI commands. */
+export type DiagnosticSurface = 'any' | 'check' | 'build' | 'dev' | 'preview' | 'test' | 'new' | 'agent' | 'doctor' | 'inspect' | 'state' | 'auth' | 'deploy' | 'deployments' | 'promote' | 'rollback' | 'disable' | 'enable' | 'delete' | 'link' | 'env' | 'token' | 'domains' | 'export' | 'import' | 'db';
+export interface DiagnosticFamily {
+    /** Numeric prefix the family owns, as it appears in a code. */
+    readonly prefix: string;
+    readonly title: string;
+    /** What the whole family is about, for an agent triaging an unknown code. */
+    readonly summary: string;
+}
+export interface DiagnosticDefinition {
+    readonly code: string;
+    readonly prefix: string;
+    /** One line: what the platform observed. */
+    readonly means: string;
+    /** One line: the edit or action that closes it. */
+    readonly repair: string;
+    /** Commands whose JSON output can carry this code. */
+    readonly surfaces: readonly DiagnosticSurface[];
+}
+export declare const DIAGNOSTIC_FAMILIES: readonly DiagnosticFamily[];
+export declare const DIAGNOSTIC_DEFINITIONS: readonly DiagnosticDefinition[];
+export declare const DIAGNOSTICS: Readonly<Record<string, DiagnosticDefinition>>;
+/** Every documented code, ascending. */
+export declare const DIAGNOSTIC_CODES: readonly string[];
+export declare function diagnosticDefinition(code: string): DiagnosticDefinition | undefined;
+/** The family a code belongs to, matched on its numeric prefix. */
+export declare function diagnosticFamily(code: string): DiagnosticFamily | undefined;
+/**
+ * Renders the agent-facing diagnostics reference. The checked-in copy under
+ * `.agents/skills/xeer/references/` is this function's canonical output; a test fails when
+ * the two diverge, so the reference cannot drift from the catalogue.
+ */
+export declare function renderDiagnosticsReference(): string;
+/** Markdown used by the public docs page and the installed offline docs bundle. */
+export declare function renderDiagnosticsDocsPage(): string;