@siteverb/contracts 0.1.0-rc.0

package/README.md

@@ -0,0 +1,25 @@
+# @siteverb/contracts
+
+Portable, versioned JSON contracts shared by the Siteverb installer skill, deterministic runner,
+GitHub Action, and future hosted control plane.
+
+## Project contract
+
+```ts
+import { parseProjectContract } from '@siteverb/contracts';
+
+const contract = parseProjectContract(JSON.parse(source));
+```
+
+The package also publishes `@siteverb/contracts/siteverb.webmcp.schema.json` for editors and
+non-TypeScript consumers. A contract defines stable tool identities, wire names, risk, examples,
+deterministic journeys, postconditions, cleanup, ownership, and evidence-labeled support profiles.
+
+Unknown fields fail validation. Tool and journey references are checked after parsing. Read-only
+annotations must agree with declared risk.
+
+## Evidence report
+
+`parseRunReport()` validates the bounded report emitted by `@siteverb/runner`. Reports contain
+browser provenance, step status, duration, and bounded errors. Raw prompts, tool inputs, tool
+results, DOM snapshots, cookies, and credentials are not part of the default report contract.

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import type { z } from 'zod';
+import { compatibilityAssessmentSchema, compatibilityFindingSchema, domExpectationSchema, journeyContractSchema, journeyReportSchema, journeyStepSchema, projectContractSchema, resultExpectationSchema, runReportSchema, stepExpectationSchema, stepReportSchema, toolContractSchema, urlExpectationSchema } from './schema.js';
+export { compatibilityAssessmentSchema, compatibilityFindingSchema, domExpectationSchema, evidenceLevelSchema, journeyContractSchema, journeyReportSchema, journeyStepSchema, jsonValueSchema, projectContractJsonSchema, projectContractSchema, resultExpectationSchema, runReportJsonSchema, runReportSchema, stepExpectationSchema, stepReportSchema, supportProfileSchema, toolAnnotationsSchema, toolContractSchema, toolExampleSchema, urlExpectationSchema, } from './schema.js';
+export type ProjectContract = z.infer<typeof projectContractSchema>;
+export type ToolContract = z.infer<typeof toolContractSchema>;
+export type JourneyContract = z.infer<typeof journeyContractSchema>;
+export type JourneyStep = z.infer<typeof journeyStepSchema>;
+export type StepExpectation = z.infer<typeof stepExpectationSchema>;
+export type ResultExpectation = z.infer<typeof resultExpectationSchema>;
+export type UrlExpectation = z.infer<typeof urlExpectationSchema>;
+export type DomExpectation = z.infer<typeof domExpectationSchema>;
+export type StepReport = z.infer<typeof stepReportSchema>;
+export type JourneyReport = z.infer<typeof journeyReportSchema>;
+export type CompatibilityFinding = z.infer<typeof compatibilityFindingSchema>;
+export type CompatibilityAssessment = z.infer<typeof compatibilityAssessmentSchema>;
+export type RunReport = z.infer<typeof runReportSchema>;
+export type { JsonValue } from './schema.js';
+export declare function parseProjectContract(input: unknown): ProjectContract;
+export declare function parseRunReport(input: unknown): RunReport;
+export declare function safeParseProjectContract(input: unknown): z.ZodSafeParseResult<{
+    $schema?: string | undefined;
+    version: 1;
+    project: string;
+    support: {
+        id: string;
+        version: string;
+        evidence: "documented-profile" | "official-sdk" | "real-browser" | "real-client";
+    }[];
+    tools: {
+        id: string;
+        name: string;
+        title?: string | undefined;
+        description: string;
+        inputSchema?: Record<string, unknown> | undefined;
+        annotations?: {
+            readOnlyHint?: boolean | undefined;
+            untrustedContentHint?: boolean | undefined;
+        } | undefined;
+        risk: "consequential" | "read-only" | "reversible";
+        registration: "declarative" | "imperative";
+        frame: "cross-origin-iframe" | "same-origin-iframe" | "top-level";
+        routes?: string[] | undefined;
+        owners?: string[] | undefined;
+        examples: {
+            name: string;
+            input: Record<string, import("./schema.js").JsonValue>;
+        }[];
+    }[];
+    journeys: {
+        id: string;
+        name: string;
+        description?: string | undefined;
+        start: string;
+        auth?: string | undefined;
+        owners?: string[] | undefined;
+        steps: {
+            tool: string;
+            input: Record<string, import("./schema.js").JsonValue>;
+            expect?: {
+                result?: {
+                    equals?: import("./schema.js").JsonValue | undefined;
+                    contains?: import("./schema.js").JsonValue | undefined;
+                } | undefined;
+                url?: {
+                    pathname?: string | undefined;
+                    searchParams?: Record<string, string> | undefined;
+                } | undefined;
+                dom?: {
+                    selector: string;
+                    state: "attached" | "detached" | "hidden" | "visible";
+                    textContains?: string | undefined;
+                    attribute?: {
+                        name: string;
+                        equals: string;
+                    } | undefined;
+                }[] | undefined;
+            } | undefined;
+        }[];
+        cleanup?: {
+            tool: string;
+            input: Record<string, import("./schema.js").JsonValue>;
+            expect?: {
+                result?: {
+                    equals?: import("./schema.js").JsonValue | undefined;
+                    contains?: import("./schema.js").JsonValue | undefined;
+                } | undefined;
+                url?: {
+                    pathname?: string | undefined;
+                    searchParams?: Record<string, string> | undefined;
+                } | undefined;
+                dom?: {
+                    selector: string;
+                    state: "attached" | "detached" | "hidden" | "visible";
+                    textContains?: string | undefined;
+                    attribute?: {
+                        name: string;
+                        equals: string;
+                    } | undefined;
+                }[] | undefined;
+            } | undefined;
+        }[] | undefined;
+        policy: {
+            requireHumanBefore: string[];
+        };
+    }[];
+}>;
+export declare function safeParseRunReport(input: unknown): z.ZodSafeParseResult<{
+    version: 1;
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    targetUrl: string;
+    project: string;
+    contractHash: string;
+    runner: {
+        name: string;
+        version: string;
+    };
+    browser: {
+        name: string;
+        version: string;
+        channel: string;
+        evidence: "documented-profile" | "official-sdk" | "real-browser" | "real-client" | "spec-only";
+    };
+    summary: {
+        passed: number;
+        failed: number;
+        skipped: number;
+    };
+    compatibility: {
+        profileId: string;
+        status: "compatible" | "incompatible" | "unknown";
+        findings: {
+            code: string;
+            evidence: "documented-profile" | "official-sdk" | "real-browser" | "real-client" | "spec-only";
+            message: string;
+            severity: "error" | "warning";
+            source: string;
+            toolId: string;
+        }[];
+    }[];
+    journeys: {
+        id: string;
+        name: string;
+        status: "failed" | "passed" | "skipped";
+        durationMs: number;
+        steps: {
+            index: number;
+            toolId: string;
+            toolName: string;
+            status: "failed" | "passed" | "skipped";
+            durationMs: number;
+            error?: string | undefined;
+        }[];
+        cleanup: {
+            index: number;
+            toolId: string;
+            toolName: string;
+            status: "failed" | "passed" | "skipped";
+            durationMs: number;
+            error?: string | undefined;
+        }[];
+        error?: string | undefined;
+    }[];
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAEpE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAExD;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEtD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEhD"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { compatibilityAssessmentSchema, compatibilityFindingSchema, domExpectationSchema, journeyContractSchema, journeyReportSchema, journeyStepSchema, projectContractSchema, resultExpectationSchema, runReportSchema, stepExpectationSchema, stepReportSchema, toolContractSchema, urlExpectationSchema, } from './schema.js';
+export { compatibilityAssessmentSchema, compatibilityFindingSchema, domExpectationSchema, evidenceLevelSchema, journeyContractSchema, journeyReportSchema, journeyStepSchema, jsonValueSchema, projectContractJsonSchema, projectContractSchema, resultExpectationSchema, runReportJsonSchema, runReportSchema, stepExpectationSchema, stepReportSchema, supportProfileSchema, toolAnnotationsSchema, toolContractSchema, toolExampleSchema, urlExpectationSchema, } from './schema.js';
+export function parseProjectContract(input) {
+    return projectContractSchema.parse(input);
+}
+export function parseRunReport(input) {
+    return runReportSchema.parse(input);
+}
+export function safeParseProjectContract(input) {
+    return projectContractSchema.safeParse(input);
+}
+export function safeParseRunReport(input) {
+    return runReportSchema.safeParse(input);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAiBrB,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC"}