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

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,62 @@
+# @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
+```
+
+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",
+  provides: [{ id: "example.task", version: "1.0.0" }],
+  resources: [
+    { kind: "contract", source: "_contracts/example.task.md", document: contractDocument },
+    { kind: "type", source: "_types/task.md", document: typeDocument }
+  ]
+});
+```
+
+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,118 @@
+import { MdbaseCollectionClient, type MdbaseCollectionTransport } from "@mdbase-dev/connect";
+import type { CollectionDescription, CollectionOperation, JsonObject, TypePackProvision } from "@mdbase-dev/connect-protocol";
+export interface ValidationIssue {
+    path: string;
+    keyword: string;
+    message: string;
+    params: Record<string, unknown>;
+}
+export type ValidationResult = {
+    valid: true;
+    issues: [];
+} | {
+    valid: false;
+    issues: ValidationIssue[];
+};
+export interface ManifestValidationOptions {
+    /** Allow HTTP only for localhost/loopback developer manifests. */
+    allowLocal?: boolean;
+}
+export declare function validateAppManifest(value: unknown, options?: ManifestValidationOptions): ValidationResult;
+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";
+    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[];
+    provides: Array<{
+        id: string;
+        version: string;
+    }>;
+}
+/**
+ * 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;
+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;
+}
+export declare function formatValidationIssues(issues: ValidationIssue[]): string;

package/dist/index.js

@@ -0,0 +1,566 @@
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { MdbaseCollectionClient, MdbaseConnectError } from "@mdbase-dev/connect";
+import { isNativeRedirectUri } from "@mdbase-dev/connect-protocol";
+import appManifestSchema from "@mdbase-dev/connect-protocol/schemas/mdbase-app.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" };
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    formats: { "date-time": true, uri: true }
+});
+ajv.addSchema(appManifestSchema);
+ajv.addSchema(dataContractSchema);
+ajv.addSchema(connectProtocolSchema);
+const appManifestValidator = requiredValidator(String(appManifestSchema.$id));
+const contractValidator = requiredValidator(String(dataContractSchema.$id));
+export function validateAppManifest(value, options = {}) {
+    const candidate = options.allowLocal ? localManifestSchemaCandidate(value) : value;
+    const schemaResult = validationResult(appManifestValidator, candidate);
+    if (!schemaResult.valid)
+        return schemaResult;
+    const originResult = validateManifestOrigins(value, options.allowLocal === true);
+    if (!originResult.valid)
+        return originResult;
+    return validateProvisionRequirements(value);
+}
+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 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, source, target = source, document }) => ({
+                kind,
+                source,
+                target,
+                digest: `sha256:${createHash("sha256").update(document).digest("hex")}`
+            }))
+        },
+        resources: definition.resources.map(({ source, document }) => ({ source, document })),
+        provides: definition.provides.map((contract) => ({ ...contract }))
+    };
+    const result = validateProtocolValue(provision, "typePackProvision");
+    if (!result.valid)
+        throw new TypePackDefinitionError(result.issues);
+    return provision;
+}
+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 new MdbaseConnectError("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 new MdbaseConnectError("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()
+    };
+}
+export function formatValidationIssues(issues) {
+    return issues.map((issue) => `${issue.path || "/"} ${issue.message}`).join("; ");
+}
+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 validateManifestOrigins(value, allowLocal) {
+    const manifest = asObject(value);
+    try {
+        const homepage = new URL(String(manifest.homepage));
+        if (!secureOrAllowedLocal(homepage, allowLocal)) {
+            return semanticIssue("/homepage", "must use HTTPS (or loopback HTTP in local mode)");
+        }
+        for (const [index, redirect] of manifest.redirect_uris.entries()) {
+            const url = new URL(String(redirect));
+            if (url.origin === homepage.origin && !secureOrAllowedLocal(url, allowLocal)) {
+                return semanticIssue(`/redirect_uris/${index}`, "must use HTTPS (or loopback HTTP in local mode)");
+            }
+            const nativeAllowed = nativeRedirectMatchesApplication(url, String(manifest.id));
+            if (url.origin !== homepage.origin && !nativeAllowed) {
+                return semanticIssue(`/redirect_uris/${index}`, "must use the homepage origin or a private-use scheme matching the application ID");
+            }
+        }
+        if (manifest.icon !== undefined && new URL(String(manifest.icon)).origin !== homepage.origin) {
+            return semanticIssue("/icon", "must use the homepage origin");
+        }
+        return { valid: true, issues: [] };
+    }
+    catch {
+        return semanticIssue("/", "contains an invalid URL");
+    }
+}
+function nativeRedirectMatchesApplication(url, applicationId) {
+    const scheme = url.protocol.slice(0, -1);
+    return isNativeRedirectUri(url)
+        && (scheme === applicationId || scheme.startsWith(`${applicationId}.`));
+}
+function validateProvisionRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const requiredContracts = Array.isArray(requirements.contracts) ? requirements.contracts : [];
+    const required = new Set(requiredContracts.map((contract) => {
+        const value = asObject(contract);
+        return `${value.id}@${value.version}`;
+    }));
+    const provisions = asObject(manifest.provisions);
+    const packs = Array.isArray(provisions.type_packs)
+        ? provisions.type_packs
+        : [];
+    for (const [packIndex, provisionValue] of packs.entries()) {
+        const provision = asObject(provisionValue);
+        const providedContracts = Array.isArray(provision.provides)
+            ? provision.provides
+            : [];
+        for (const providedValue of providedContracts) {
+            const provided = asObject(providedValue);
+            if (!required.has(`${provided.id}@${provided.version}`)) {
+                return semanticIssue(`/provisions/type_packs/${packIndex}/provides`, "may only contain contracts required by the application");
+            }
+        }
+        const manifest = asObject(provision.manifest);
+        const declaredResources = Array.isArray(manifest.resources)
+            ? manifest.resources.map(asObject)
+            : [];
+        const embeddedResources = Array.isArray(provision.resources)
+            ? provision.resources.map(asObject)
+            : [];
+        const embedded = new Map(embeddedResources.map((resource) => [
+            String(resource.source),
+            resource.document
+        ]));
+        if (embedded.size !== embeddedResources.length
+            || declaredResources.length !== embeddedResources.length) {
+            return semanticIssue(`/provisions/type_packs/${packIndex}/resources`, "must match manifest source paths exactly");
+        }
+        for (const [resourceIndex, resource] of declaredResources.entries()) {
+            const source = String(resource.source);
+            const document = embedded.get(source);
+            if (typeof document !== "string") {
+                return semanticIssue(`/provisions/type_packs/${packIndex}/resources`, `is missing manifest source ${source}`);
+            }
+            const digest = `sha256:${createHash("sha256").update(document).digest("hex")}`;
+            if (digest !== resource.digest) {
+                return semanticIssue(`/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/digest`, "does not match the embedded document");
+            }
+        }
+    }
+    return { valid: true, issues: [] };
+}
+function localManifestSchemaCandidate(value) {
+    const candidate = clone(value);
+    const object = asObject(candidate);
+    for (const field of ["homepage", "icon"]) {
+        if (typeof object[field] === "string")
+            object[field] = schemaSafeLocalUrl(object[field]);
+    }
+    if (Array.isArray(object.redirect_uris)) {
+        object.redirect_uris = object.redirect_uris.map((url) => typeof url === "string" ? schemaSafeLocalUrl(url) : url);
+    }
+    return candidate;
+}
+function schemaSafeLocalUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "http:" && isLoopback(url.hostname))
+            url.protocol = "https:";
+        return url.href;
+    }
+    catch {
+        return value;
+    }
+}
+function secureOrAllowedLocal(url, allowLocal) {
+    return url.protocol === "https:"
+        || (allowLocal && url.protocol === "http:" && isLoopback(url.hostname));
+}
+function isLoopback(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+function semanticIssue(path, message) {
+    return {
+        valid: false,
+        issues: [{ path, keyword: "semantic", message, params: {} }]
+    };
+}
+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", "install_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 new MdbaseConnectError("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 new MdbaseConnectError("invalid_request", `${field} must be a non-empty string.`);
+    }
+    return value;
+}
+function integer(value, field, minimum) {
+    if (!Number.isInteger(value) || Number(value) < minimum) {
+        throw new MdbaseConnectError("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,41 @@
+{
+  "name": "@mdbase-dev/connect-dev",
+  "version": "0.1.0-beta.21",
+  "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",
+    "@mdbase-dev/connect": "0.1.0-beta.21",
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.21"
+  },
+  "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",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}