@mdbase-dev/connect-dev 0.1.0-beta.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdbase connect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @mdbase-dev/connect-dev
+
+Developer tools for applications built on mdbase connect.
+
+The package provides canonical manifest and data-contract validation plus an
+in-memory transport for frontend tests. The sandbox supports typed CRUD,
+revision preconditions, read defaults, type-filtered pagination, and change
+cursors. It rejects CEL filters and ordering so semantic tests cannot silently
+depend on an approximation; run those against a real connector.
+
+```ts
+import { createSandbox } from "@mdbase-dev/connect-dev";
+
+const { client } = createSandbox({
+  records: [{
+    path: "tasks/first.md",
+    types: ["task"],
+    frontmatter: { type: "task", title: "First" }
+  }]
+});
+
+const tasks = await client.query({ types: ["task"] });
+```
+
+Validate artifacts from a project script:
+
+```sh
+mdbase-connect-dev validate-manifest public/.well-known/mdbase-app.json
+mdbase-connect-dev validate-manifest public/.well-known/mdbase-app.json --allow-local
+mdbase-connect-dev validate-contract worklog-contract.json
+```
+
+Manifest validation uses the same canonical JSON Schema, semantic checks,
+embedded-resource digest verification, and declaration-size bound as the
+matching Connect server. Run it against the generated artifact in application
+CI—not only against a handwritten source object. Failures include the exact
+JSON-pointer path and rule.
+
+Deployed applications can also submit `{ "manifest": ... }` to
+`POST /v1/apps/validate`. That endpoint performs the same validation without
+creating or updating an application registration, making it suitable for
+release smoke tests.
+
+Bundled application declarations support connector-controlled type-pack
+provisioning. Put the contract, its implementing types, and any referenced
+schemas in one `provisions.type_packs` transaction. Each manifest entry pins
+the exact destination and SHA-256 digest. `provides` declares which exact
+contracts the pack satisfies; auxiliary types belong in the same pack. The
+validator rejects missing sources, digest mismatches, and claims for contracts
+the application does not require.
+
+Use `defineTypePack` to generate the manifest entries and digests from readable
+documents:
+
+```ts
+import { defineTypePack } from "@mdbase-dev/connect-dev";
+
+const provision = defineTypePack({
+  id: "example.tasks",
+  version: "1.0.0",
+  resources: [
+    {
+      kind: "contract",
+      mode: "managed",
+      source: "_contracts/example.task.md",
+      document: contractDocument
+    },
+    {
+      kind: "type",
+      mode: "seed",
+      source: "_types/task.md",
+      document: typeDocument
+    }
+  ]
+});
+```
+
+The helper validates each contract document and derives the exact semantic
+`provides` descriptors. Managed resources evolve with the pack; seed resources
+become collection-owned after their initial creation.
+
+Native applications may add a reverse-domain private-use callback scheme that
+matches the v1 manifest's application ID, such as
+`example.tasks.desktop://auth/mdbase/callback` for
+`id: "example.tasks.desktop"`. Native authorization still uses PKCE and should
+open the authorization URL in the system browser.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { formatValidationIssues, validateAppManifest, validateDataContract } from "./index.js";
+const arguments_ = process.argv.slice(2);
+const allowLocal = arguments_.includes("--allow-local");
+const [command, source] = arguments_.filter((argument) => argument !== "--allow-local");
+if (!source || !["validate-manifest", "validate-contract"].includes(command ?? "")) {
+    console.error("Usage: mdbase-connect-dev <validate-manifest|validate-contract> <file.json> [--allow-local]");
+    process.exitCode = 2;
+}
+else {
+    try {
+        const value = JSON.parse(await readFile(resolve(source), "utf8"));
+        const result = command === "validate-manifest"
+            ? validateAppManifest(value, { allowLocal })
+            : validateDataContract(value);
+        if (result.valid) {
+            console.log(`${source} is valid`);
+        }
+        else {
+            console.error(formatValidationIssues(result.issues));
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { MdbaseCollectionClient, type MdbaseCollectionTransport } from "@mdbase-dev/connect/advanced";
+import type { CollectionDescription, CollectionOperation, JsonObject, TypePackProvision } from "@mdbase-dev/connect-protocol";
+import { formatManifestValidationIssues, validateAppManifest, type ManifestValidationIssue, type ManifestValidationOptions, type ManifestValidationResult } from "@mdbase-dev/connect-protocol/manifest";
+export type ValidationIssue = ManifestValidationIssue;
+export type ValidationResult = ManifestValidationResult;
+export type { ManifestValidationOptions };
+export { validateAppManifest };
+export declare const formatValidationIssues: typeof formatManifestValidationIssues;
+export declare function validateDataContract(value: unknown): ValidationResult;
+export declare function validateProtocolValue(value: unknown, definition?: string): ValidationResult;
+export interface DataContractDocument extends JsonObject {
+    kind: "mdbase.contract";
+    contract_type: "record" | "event" | "action";
+    id: string;
+    version: string;
+}
+export interface RecordDataContractDocument extends DataContractDocument {
+    contract_type: "record";
+    record_schema: JsonObject;
+}
+export interface EventDataContractDocument extends DataContractDocument {
+    contract_type: "event";
+    data_schema: JsonObject;
+}
+export interface ActionDataContractDocument extends DataContractDocument {
+    contract_type: "action";
+    input_schema: JsonObject;
+}
+export declare function defineDataContract<const Contract extends RecordDataContractDocument | EventDataContractDocument | ActionDataContractDocument>(contract: Contract): Contract;
+export declare class DataContractDefinitionError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+}
+export interface TypePackResourceInput {
+    kind: "contract" | "type" | "schema";
+    /** Managed resources evolve with the pack; seed resources become user-owned after creation. */
+    mode: "managed" | "seed";
+    source: string;
+    /** Collection-relative install location. Defaults to `source`. */
+    target?: string;
+    /** Exact UTF-8 resource document included in the provision. */
+    document: string;
+}
+export interface TypePackDefinition {
+    id: string;
+    version: string;
+    name?: string;
+    description?: string;
+    resources: TypePackResourceInput[];
+}
+/**
+ * Build a complete, digest-pinned type-pack provision from readable source
+ * documents. This keeps application manifests reviewable without asking
+ * developers to calculate SHA-256 values by hand.
+ */
+export declare function defineTypePack(definition: TypePackDefinition): TypePackProvision;
+/** Compute the portable semantic digest of one validated, fully resolved contract. */
+export declare function dataContractDigest(contract: Record<string, unknown>): string;
+export declare class DataContractDigestError extends Error {
+}
+export declare class TypePackDefinitionError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+}
+export interface SandboxRecord<Frontmatter extends JsonObject = JsonObject> {
+    path: string;
+    frontmatter?: Frontmatter;
+    body?: string;
+    types?: string[];
+}
+export interface SandboxOptions<Frontmatter extends JsonObject = JsonObject> {
+    description?: Partial<CollectionDescription>;
+    records?: SandboxRecord<Frontmatter>[];
+}
+export interface DeveloperSandbox<Frontmatter extends JsonObject = JsonObject> {
+    client: MdbaseCollectionClient<Frontmatter>;
+    transport: SandboxTransport<Frontmatter>;
+}
+/**
+ * Build a deterministic, in-memory provider for frontend development.
+ *
+ * It intentionally implements the transport contract, CRUD preconditions,
+ * defaults, type filtering, pagination, and change cursors. It rejects query
+ * expression features so tests cannot silently rely on a non-conformant CEL
+ * approximation; use a real connector for semantic integration tests.
+ */
+export declare function createSandbox<Frontmatter extends JsonObject = JsonObject>(options?: SandboxOptions<Frontmatter>): DeveloperSandbox<Frontmatter>;
+export declare class SandboxTransport<Frontmatter extends JsonObject = JsonObject> implements MdbaseCollectionTransport {
+    private readonly records;
+    private readonly events;
+    private revisionSequence;
+    readonly description: CollectionDescription;
+    constructor(options?: SandboxOptions<Frontmatter>);
+    seed(record: SandboxRecord<Frontmatter>): void;
+    snapshot(): SandboxRecord<Frontmatter>[];
+    operation<Result>(operation: CollectionOperation, input: unknown): Promise<Result>;
+    private changes;
+    private read;
+    private query;
+    private create;
+    private update;
+    private delete;
+    private rename;
+    private storedRecord;
+    private recordResult;
+    private append;
+}

package/dist/index.js

@@ -0,0 +1,523 @@
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { parseDocument } from "yaml";
+import { connectError, MdbaseCollectionClient } from "@mdbase-dev/connect/advanced";
+import { formatManifestValidationIssues, validateAppManifest } from "@mdbase-dev/connect-protocol/manifest";
+import connectProblemSchema from "@mdbase-dev/connect-protocol/schemas/connect-problem.v1.schema.json" with { type: "json" };
+import dataContractSchema from "@mdbase-dev/connect-protocol/schemas/data-contract.schema.json" with { type: "json" };
+import connectProtocolSchema from "@mdbase-dev/connect-protocol/schemas/connect-protocol.v1.schema.json" with { type: "json" };
+import filesSchema from "@mdbase-dev/connect-protocol/schemas/files.v1.schema.json" with { type: "json" };
+export { validateAppManifest };
+export const formatValidationIssues = formatManifestValidationIssues;
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    // `required` may name properties declared by an enclosing allOf branch.
+    strictRequired: false,
+    formats: { "date-time": true, uri: true, uuid: true }
+});
+ajv.addSchema(connectProblemSchema);
+ajv.addSchema(dataContractSchema);
+ajv.addSchema(filesSchema);
+ajv.addSchema(connectProtocolSchema);
+const contractValidator = requiredValidator(String(dataContractSchema.$id));
+export function validateDataContract(value) {
+    return validationResult(contractValidator, value);
+}
+export function validateProtocolValue(value, definition) {
+    const reference = definition
+        ? `${String(connectProtocolSchema.$id)}#/$defs/${definition}`
+        : String(connectProtocolSchema.$id);
+    return validationResult(requiredValidator(reference), value);
+}
+export function defineDataContract(contract) {
+    const result = validateDataContract(contract);
+    if (!result.valid) {
+        throw new DataContractDefinitionError(result.issues);
+    }
+    return contract;
+}
+export class DataContractDefinitionError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid data contract: ${formatValidationIssues(issues)}`);
+        this.issues = issues;
+    }
+}
+/**
+ * Build a complete, digest-pinned type-pack provision from readable source
+ * documents. This keeps application manifests reviewable without asking
+ * developers to calculate SHA-256 values by hand.
+ */
+export function defineTypePack(definition) {
+    const provides = definition.resources
+        .map((resource, index) => ({ resource, index }))
+        .filter(({ resource }) => resource.kind === "contract")
+        .map(({ resource, index }) => {
+        if (resource.mode !== "managed") {
+            throw new TypePackDefinitionError([definitionIssue(`/resources/${index}/mode`, "contract_resource_mode", "contract resources must be managed so their declared version and digest can evolve with the pack")]);
+        }
+        return exactContractReferenceFromDocument(resource.document, index);
+    })
+        .sort((left, right) => left.id.localeCompare(right.id)
+        || left.version.localeCompare(right.version)
+        || left.digest.localeCompare(right.digest));
+    const provision = {
+        manifest: {
+            kind: "mdbase.type-pack",
+            id: definition.id,
+            version: definition.version,
+            ...(definition.name ? { name: definition.name } : {}),
+            ...(definition.description ? { description: definition.description } : {}),
+            resources: definition.resources.map(({ kind, mode, source, target = source, document }) => ({
+                kind,
+                mode,
+                source,
+                target,
+                digest: `sha256:${createHash("sha256").update(document).digest("hex")}`
+            }))
+        },
+        resources: definition.resources.map(({ source, document }) => ({ source, document })),
+        provides
+    };
+    const result = validateProtocolValue(provision, "typePackProvision");
+    if (!result.valid)
+        throw new TypePackDefinitionError(result.issues);
+    return provision;
+}
+function exactContractReferenceFromDocument(document, resourceIndex) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(document)?.[1];
+    if (frontmatter === undefined) {
+        throw new TypePackDefinitionError([definitionIssue(`/resources/${resourceIndex}/document`, "contract_frontmatter", "contract resources must contain YAML frontmatter")]);
+    }
+    const parsed = parseDocument(frontmatter, { uniqueKeys: true });
+    if (parsed.errors.length > 0) {
+        throw new TypePackDefinitionError([definitionIssue(`/resources/${resourceIndex}/document`, "contract_frontmatter", `contract frontmatter is invalid: ${parsed.errors[0]?.message ?? "unknown YAML error"}`)]);
+    }
+    const contract = parsed.toJS({ maxAliasCount: 0 });
+    const validation = validateDataContract(contract);
+    if (!validation.valid)
+        throw new DataContractDefinitionError(validation.issues);
+    const value = contract;
+    return {
+        id: String(value.id),
+        version: String(value.version),
+        digest: dataContractDigest(value)
+    };
+}
+/** Compute the portable semantic digest of one validated, fully resolved contract. */
+export function dataContractDigest(contract) {
+    const validation = validateDataContract(contract);
+    if (!validation.valid)
+        throw new DataContractDefinitionError(validation.issues);
+    const contractType = String(contract.contract_type);
+    const portable = {
+        kind: contract.kind,
+        contract_type: contract.contract_type,
+        id: contract.id,
+        version: contract.version
+    };
+    const schemaFields = contractType === "record"
+        ? ["record_schema", "binding_schema"]
+        : contractType === "event"
+            ? ["data_schema", "source_schema"]
+            : ["input_schema", "output_schema", "error_schema", "provider_schema"];
+    for (const field of schemaFields) {
+        const wrapper = contract[field];
+        if (wrapper === undefined)
+            continue;
+        if (!isRecord(wrapper) || !("value" in wrapper)) {
+            throw new DataContractDigestError(`${field} must be resolved to an inline JSON Schema before calculating a contract digest.`);
+        }
+        portable[field] = structuredClone(wrapper.value);
+    }
+    if (contractType === "action" && contract.behavior !== undefined) {
+        portable.behavior = structuredClone(contract.behavior);
+    }
+    return `sha256:${createHash("sha256").update(canonicalJson(portable)).digest("hex")}`;
+}
+export class DataContractDigestError extends Error {
+}
+export class TypePackDefinitionError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid type pack: ${formatValidationIssues(issues)}`);
+        this.issues = issues;
+    }
+}
+/**
+ * Build a deterministic, in-memory provider for frontend development.
+ *
+ * It intentionally implements the transport contract, CRUD preconditions,
+ * defaults, type filtering, pagination, and change cursors. It rejects query
+ * expression features so tests cannot silently rely on a non-conformant CEL
+ * approximation; use a real connector for semantic integration tests.
+ */
+export function createSandbox(options = {}) {
+    const transport = new SandboxTransport(options);
+    return { transport, client: new MdbaseCollectionClient(transport) };
+}
+export class SandboxTransport {
+    records = new Map();
+    events = [];
+    revisionSequence = 0;
+    description;
+    constructor(options = {}) {
+        this.description = sandboxDescription(options.description);
+        for (const record of options.records ?? [])
+            this.seed(record);
+        this.events.length = 0;
+    }
+    seed(record) {
+        assertSafePath(record.path);
+        this.records.set(record.path, this.storedRecord({
+            ...record,
+            frontmatter: asObject(record.frontmatter)
+        }));
+    }
+    snapshot() {
+        return [...this.records.values()]
+            .sort((left, right) => left.path.localeCompare(right.path))
+            .map((record) => ({
+            path: record.path,
+            frontmatter: clone(record.frontmatter),
+            body: record.body,
+            types: [...record.types]
+        }));
+    }
+    async operation(operation, input) {
+        const object = asObject(input);
+        let result;
+        switch (operation) {
+            case "describe":
+                result = clone(this.description);
+                break;
+            case "changes":
+                result = this.changes(object);
+                break;
+            case "read":
+                result = this.read(object);
+                break;
+            case "query":
+                result = this.query(object);
+                break;
+            case "validate":
+                result = envelope({});
+                break;
+            case "create":
+                result = this.create(object);
+                break;
+            case "update":
+                result = this.update(object);
+                break;
+            case "delete":
+                result = this.delete(object);
+                break;
+            case "rename":
+                result = this.rename(object);
+                break;
+            default: throw connectError("unsupported_operation", `Unsupported sandbox operation: ${operation}`);
+        }
+        return clone(result);
+    }
+    changes(input) {
+        const current = this.events.length;
+        if (input.after === undefined) {
+            return { events: [], cursor: current, has_more: false, reset: false };
+        }
+        const after = integer(input.after, "after", 0);
+        const limit = integer(input.limit ?? 200, "limit", 1);
+        const available = this.events.filter((event) => event.cursor > after);
+        const events = available.slice(0, limit);
+        return {
+            events,
+            cursor: events.at(-1)?.cursor ?? after,
+            has_more: available.length > events.length,
+            reset: false
+        };
+    }
+    read(input) {
+        const path = string(input.path, "path");
+        const record = this.records.get(path);
+        if (!record)
+            return invalid("file_not_found", `File not found: ${path}`, path);
+        return envelope(this.recordResult(record));
+    }
+    query(input) {
+        if (input.where !== undefined || input.order_by !== undefined) {
+            throw connectError("sandbox_unsupported", "The in-memory sandbox does not emulate CEL or ordering. Run this test against a real connector.");
+        }
+        const types = Array.isArray(input.types)
+            ? input.types.filter((value) => typeof value === "string")
+            : [];
+        const all = [...this.records.values()]
+            .filter((record) => types.length === 0 || record.types.some((type) => types.includes(type)))
+            .sort((left, right) => left.path.localeCompare(right.path));
+        const offset = integer(input.offset ?? 0, "offset", 0);
+        const limit = integer(input.limit ?? all.length, "limit", 0);
+        const selected = all.slice(offset, offset + limit).map((record) => {
+            const document = this.recordResult(record);
+            const result = {
+                path: document.path,
+                types: document.types,
+                file: { ...document.file, path: document.path }
+            };
+            const mode = input.frontmatter_mode ?? "effective";
+            if (mode === "persisted" || mode === "both") {
+                result.frontmatter = document.frontmatter;
+            }
+            if (mode === "effective" || mode === "both") {
+                result.effective_frontmatter = document.effective_frontmatter;
+            }
+            if (input.include_body !== true)
+                delete result.body;
+            else
+                result.body = document.body;
+            return result;
+        });
+        return envelope({
+            results: selected,
+            meta: {
+                total_count: all.length,
+                has_more: offset + selected.length < all.length
+            }
+        });
+    }
+    create(input) {
+        const path = string(input.path, "path");
+        assertSafePath(path);
+        if (this.records.has(path))
+            return invalid("path_conflict", `File already exists: ${path}`, path);
+        if (input.if_revision !== undefined) {
+            return invalid("concurrent_modification", `File does not match the requested revision: ${path}`, path);
+        }
+        const frontmatter = asObject(input.frontmatter);
+        const type = typeof input.type === "string" ? input.type.toLowerCase() : undefined;
+        const record = this.storedRecord({
+            path,
+            frontmatter,
+            body: typeof input.body === "string" ? input.body : "",
+            types: type ? [type] : explicitTypes(frontmatter)
+        });
+        this.records.set(path, record);
+        this.append("mdbase.record.created", record, { path, types: record.types });
+        return envelope(this.recordResult(record));
+    }
+    update(input) {
+        const path = string(input.path, "path");
+        const current = this.records.get(path);
+        if (!current)
+            return invalid("file_not_found", `File not found: ${path}`, path);
+        const revisionError = checkRevision(input, current);
+        if (revisionError)
+            return revisionError;
+        const patch = asObject(input.patch ?? {});
+        const frontmatter = clone(current.frontmatter);
+        for (const [field, value] of Object.entries(patch))
+            frontmatter[field] = clone(value);
+        const record = this.storedRecord({
+            path,
+            frontmatter: frontmatter,
+            body: typeof input.body === "string" ? input.body : current.body,
+            types: explicitTypes(frontmatter).length > 0 ? explicitTypes(frontmatter) : current.types
+        });
+        this.records.set(path, record);
+        this.append("mdbase.record.modified", record, { path, types: record.types, changed_fields: Object.keys(patch) });
+        return envelope(this.recordResult(record));
+    }
+    delete(input) {
+        const path = string(input.path, "path");
+        const current = this.records.get(path);
+        if (!current)
+            return invalid("file_not_found", `File not found: ${path}`, path);
+        const revisionError = checkRevision(input, current);
+        if (revisionError)
+            return revisionError;
+        if (input.dry_run === true) {
+            return envelope({
+                path,
+                deleted: false,
+                dry_run: true,
+                would_delete: true
+            });
+        }
+        this.records.delete(path);
+        this.append("mdbase.record.deleted", current, { path, types: current.types });
+        return envelope({ path, deleted: true });
+    }
+    rename(input) {
+        const from = string(input.from, "from");
+        const to = string(input.to, "to");
+        assertSafePath(to);
+        const current = this.records.get(from);
+        if (!current)
+            return invalid("file_not_found", `File not found: ${from}`, from);
+        const revisionError = checkRevision(input, current);
+        if (revisionError)
+            return revisionError;
+        if (this.records.has(to))
+            return invalid("path_conflict", `File already exists: ${to}`, to);
+        if (input.dry_run === true) {
+            return envelope({
+                from,
+                to,
+                dry_run: true,
+                would_rename: true
+            });
+        }
+        this.records.delete(from);
+        const record = this.storedRecord({ ...current, path: to });
+        this.records.set(to, record);
+        this.append("mdbase.record.renamed", record, { from, to, types: record.types });
+        return envelope({ ...this.recordResult(record), from, to, references_updated: [] });
+    }
+    storedRecord(record) {
+        return {
+            path: record.path,
+            frontmatter: clone(record.frontmatter),
+            body: record.body ?? "",
+            types: [...(record.types ?? explicitTypes(record.frontmatter))],
+            revision: `sandbox:${++this.revisionSequence}`
+        };
+    }
+    recordResult(record) {
+        const effective = clone(record.frontmatter);
+        for (const typeName of record.types) {
+            const type = this.description.types.find((candidate) => candidate.name === typeName);
+            const defaults = asObject(type?.collection?.read_defaults);
+            for (const [field, value] of Object.entries(defaults)) {
+                if (!(field in effective))
+                    effective[field] = clone(value);
+            }
+        }
+        return {
+            path: record.path,
+            frontmatter: clone(record.frontmatter),
+            effective_frontmatter: effective,
+            body: record.body,
+            types: [...record.types],
+            revision: record.revision,
+            file: sandboxFileMetadata(record)
+        };
+    }
+    append(type, record, payload) {
+        const cursor = this.events.length + 1;
+        this.events.push({
+            cursor,
+            type,
+            occurred_at: new Date(cursor).toISOString(),
+            payload: { ...clone(payload), revision: record.revision }
+        });
+    }
+}
+function sandboxFileMetadata(record) {
+    const segments = record.path.split("/");
+    const name = segments.at(-1) ?? record.path;
+    const folder = segments.slice(0, -1).join("/");
+    const revision = Number(record.revision.split(":").at(-1) ?? 0);
+    const serialized = `---\n${JSON.stringify(record.frontmatter)}\n---\n${record.body}`;
+    return {
+        name,
+        folder,
+        size: new TextEncoder().encode(serialized).byteLength,
+        mtime: new Date(revision).toISOString()
+    };
+}
+function requiredValidator(reference) {
+    const validate = ajv.getSchema(reference);
+    if (!validate)
+        throw new Error(`Canonical schema is unavailable: ${reference}`);
+    return validate;
+}
+function validationResult(validate, value) {
+    if (validate(value))
+        return { valid: true, issues: [] };
+    return {
+        valid: false,
+        issues: (validate.errors ?? []).map(validationIssue)
+    };
+}
+function validationIssue(error) {
+    return {
+        path: error.instancePath,
+        keyword: error.keyword,
+        message: error.message ?? "is invalid",
+        params: error.params
+    };
+}
+function definitionIssue(path, keyword, message) {
+    return { path, keyword, message, params: {} };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+        .join(",")}}`;
+}
+function sandboxDescription(value = {}) {
+    return {
+        protocol_version: 1,
+        collection_id: value.collection_id ?? "01900000-0000-7000-8000-000000000001",
+        display_name: value.display_name ?? "Developer sandbox",
+        spec_version: value.spec_version ?? "0.3.0",
+        operations: value.operations ?? ["describe", "changes", "read", "query", "list_views", "execute_view", "read_view_source", "validate", "create", "update", "delete", "rename", "create_view_source", "update_view_source", "delete_view_source", "read_type", "create_type", "update_type", "assess_type_pack", "apply_type_pack"],
+        change_cursor: value.change_cursor ?? 0,
+        types: clone(value.types ?? []),
+        contracts: clone(value.contracts ?? [])
+    };
+}
+function envelope(result) {
+    return { valid: true, result: result, diagnostics: [] };
+}
+function invalid(code, message, path) {
+    return {
+        valid: false,
+        result: {},
+        diagnostics: [{ severity: "error", code, message, path }]
+    };
+}
+function checkRevision(input, record) {
+    if (input.if_revision === undefined || input.if_revision === record.revision)
+        return null;
+    return invalid("concurrent_modification", `File does not match the requested revision: ${record.path}`, record.path);
+}
+function explicitTypes(frontmatter) {
+    const values = [frontmatter.type, frontmatter.types]
+        .flatMap((value) => Array.isArray(value) ? value : [value])
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .map((value) => value.toLowerCase());
+    return [...new Set(values)];
+}
+function assertSafePath(path) {
+    if (!path || path.startsWith("/") || path.includes("\\") || path.split("/").includes("..")) {
+        throw connectError("invalid_path", `Unsafe sandbox path: ${path}`);
+    }
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function string(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw connectError("invalid_request", `${field} must be a non-empty string.`);
+    }
+    return value;
+}
+function integer(value, field, minimum) {
+    if (!Number.isInteger(value) || Number(value) < minimum) {
+        throw connectError("invalid_request", `${field} must be an integer of at least ${minimum}.`);
+    }
+    return Number(value);
+}
+function clone(value) {
+    return structuredClone(value);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mdbase-dev/connect-dev",
+  "version": "0.1.0-beta.100",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdbase-dev/mdbase-connect.git",
+    "directory": "packages/devkit"
+  },
+  "homepage": "https://mdbase.dev",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mdbase-connect-dev": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "yaml": "^2.9.0",
+    "@mdbase-dev/connect": "0.1.0-beta.100",
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.100"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/cli.js',0o755)\"",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}