@mdbase-dev/connect-dev 0.1.0-beta.26 → 0.1.0-beta.28

package/README.md

@@ -47,14 +47,27 @@ 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 }
+    {
+      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

package/dist/index.d.ts

@@ -45,6 +45,8 @@ export declare class DataContractDefinitionError extends Error {
 }
 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;
@@ -57,10 +59,6 @@ export interface TypePackDefinition {
     name?: string;
     description?: string;
     resources: TypePackResourceInput[];
-    provides: Array<{
-        id: string;
-        version: string;
-    }>;
 }
 /**
  * Build a complete, digest-pinned type-pack provision from readable source
@@ -68,6 +66,10 @@ export interface TypePackDefinition {
  * 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[]);

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { Ajv2020 } from "ajv/dist/2020.js";
+import { parseDocument } from "yaml";
 import { MdbaseCollectionClient, connectError } 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" };
@@ -29,6 +30,9 @@ export function validateAppManifest(value, options = {}) {
     const originResult = validateManifestOrigins(value, options.allowLocal === true);
     if (!originResult.valid)
         return originResult;
+    const capabilityResult = validateCapabilityRequirements(value);
+    if (!capabilityResult.valid)
+        return capabilityResult;
     return validateProvisionRequirements(value);
 }
 export function validateDataContract(value) {
@@ -60,6 +64,18 @@ export class DataContractDefinitionError extends Error {
  * 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",
@@ -67,21 +83,75 @@ export function defineTypePack(definition) {
             version: definition.version,
             ...(definition.name ? { name: definition.name } : {}),
             ...(definition.description ? { description: definition.description } : {}),
-            resources: definition.resources.map(({ kind, source, target = source, document }) => ({
+            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: definition.provides.map((contract) => ({ ...contract }))
+        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) {
@@ -475,6 +545,63 @@ function validateProvisionRequirements(value) {
     }
     return { valid: true, issues: [] };
 }
+function validateCapabilityRequirements(value) {
+    const manifest = asObject(value);
+    const requirements = asObject(manifest.requirements);
+    const capabilities = asObject(requirements.capabilities);
+    if (Object.keys(capabilities).length === 0)
+        return { valid: true, issues: [] };
+    const required = Array.isArray(capabilities.required)
+        ? capabilities.required.map(String)
+        : [];
+    const optional = Array.isArray(capabilities.optional)
+        ? capabilities.optional.map(String)
+        : [];
+    if (new Set(required).size !== required.length) {
+        return semanticIssue("/requirements/capabilities/required", "must not contain duplicates");
+    }
+    if (new Set(optional).size !== optional.length) {
+        return semanticIssue("/requirements/capabilities/optional", "must not contain duplicates");
+    }
+    const overlap = optional.find((capability) => required.includes(capability));
+    if (overlap) {
+        return semanticIssue("/requirements/capabilities/optional", `must not repeat required capability ${overlap}`);
+    }
+    const declared = new Set([...required, ...optional]);
+    const provisions = asObject(manifest.provisions);
+    if (Array.isArray(requirements.contracts)
+        && requirements.contracts.length > 0
+        && requirements.access !== "full_collection"
+        && !required.includes("definitions.contracts.current")) {
+        return semanticIssue("/requirements/capabilities/required", "must require definitions.contracts.current for contract-scoped requirements");
+    }
+    if (declared.has("definitions.type-pack.apply")) {
+        if (requirements.access !== "full_collection") {
+            return semanticIssue("/requirements/access", "must be full_collection for definitions.type-pack.apply");
+        }
+        if (!required.includes("definitions.type-pack.apply")) {
+            return semanticIssue("/requirements/capabilities/required", "must require definitions.type-pack.apply when it is declared");
+        }
+        if (!Array.isArray(provisions.type_packs) || provisions.type_packs.length === 0) {
+            return semanticIssue("/provisions/type_packs", "must contain a pack for definitions.type-pack.apply");
+        }
+    }
+    if (declared.has("notifications.background-delivery")
+        && !Array.isArray(asObject(manifest.notifications).criteria)) {
+        return semanticIssue("/notifications/criteria", "must be declared for notifications.background-delivery");
+    }
+    const fileRequirement = asObject(requirements.files);
+    const fileActions = Array.isArray(fileRequirement.actions)
+        ? new Set(fileRequirement.actions.map(String))
+        : new Set();
+    for (const action of ["list", "read", "add", "replace", "move", "delete"]) {
+        const capability = `files.${action}`;
+        if (declared.has(capability) !== fileActions.has(action)) {
+            return semanticIssue("/requirements/capabilities", `${capability} and requirements.files.actions.${action} must be declared together`);
+        }
+    }
+    return { valid: true, issues: [] };
+}
 function localManifestSchemaCandidate(value) {
     const candidate = clone(value);
     const object = asObject(candidate);
@@ -511,13 +638,30 @@ function semanticIssue(path, message) {
         issues: [{ path, keyword: "semantic", message, 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", "install_type_pack"],
+        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 ?? [])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-dev",
-  "version": "0.1.0-beta.26",
+  "version": "0.1.0-beta.28",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -25,8 +25,9 @@
   ],
   "dependencies": {
     "ajv": "^8.20.0",
-    "@mdbase-dev/connect": "0.1.0-beta.26",
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.26"
+    "yaml": "^2.9.0",
+    "@mdbase-dev/connect": "0.1.0-beta.28",
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.28"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",