@openship/protocol 0.0.1

package/dist/skill/references/schemas/sources-bundle.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openship.dev/schemas/sources-bundle.schema.json",
+  "title": "OpenShip Sources v1 bundle",
+  "type": "object",
+  "required": ["openship", "capability", "digest", "files"],
+  "properties": {
+    "openship": { "const": "1.0" },
+    "capability": { "const": "sources" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "files": {
+      "type": "object",
+      "propertyNames": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[^\\u0000]+$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["encoding", "content"],
+        "properties": {
+          "encoding": { "enum": ["utf-8", "base64"] },
+          "content": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/dist/skill/references/schemas/sources-manifest.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openship.dev/schemas/sources-manifest.schema.json",
+  "title": "OpenShip Sources v1 manifest",
+  "type": "object",
+  "required": ["openship", "capability", "digest", "project", "totals", "files"],
+  "properties": {
+    "openship": { "const": "1.0" },
+    "capability": { "const": "sources" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" },
+    "parent": { "$ref": "#/$defs/digest" },
+    "project": {
+      "type": "object",
+      "required": ["name", "description"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "homepage": { "type": "string", "format": "uri" },
+        "repository": { "type": "string", "format": "uri" },
+        "license": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "commit": {
+      "type": "object",
+      "required": ["sha", "dirty"],
+      "properties": {
+        "sha": { "type": "string", "minLength": 1 },
+        "ref": { "type": "string" },
+        "committedAt": { "type": "string", "format": "date-time" },
+        "dirty": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "stack": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "structure": { "type": "array", "items": { "type": "object", "required": ["path", "purpose"], "properties": { "path": { "type": "string" }, "purpose": { "type": "string" } }, "additionalProperties": true } },
+    "setup": { "type": "object", "additionalProperties": true },
+    "env": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" }, "uniqueItems": true },
+    "ignore": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "ignoreNames": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "fileSet": { "type": "string", "minLength": 1 },
+    "totals": {
+      "type": "object",
+      "required": ["files", "bytes"],
+      "properties": {
+        "files": { "type": "integer", "minimum": 0 },
+        "bytes": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "files": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/file" }
+    }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "path": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[^\\u0000]+$" },
+    "file": {
+      "type": "object",
+      "required": ["path", "size", "sha256", "encoding", "mediaType", "type"],
+      "properties": {
+        "path": { "$ref": "#/$defs/path" },
+        "size": { "type": "integer", "minimum": 0 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "encoding": { "enum": ["utf-8", "base64"] },
+        "mediaType": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["file", "symlink"] },
+        "target": { "$ref": "#/$defs/path" }
+      },
+      "allOf": [
+        { "if": { "properties": { "type": { "const": "symlink" } }, "required": ["type"] }, "then": { "properties": { "target": { "$ref": "#/$defs/path" } }, "required": ["target"] } }
+      ],
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/dist/skill/references/schemas/systems.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openship.dev/schemas/systems.schema.json",
+  "title": "OpenShip Systems v1",
+  "type": "object",
+  "required": ["openship", "capability", "source", "system"],
+  "properties": {
+    "openship": { "const": "1.0" },
+    "capability": { "const": "systems" },
+    "source": {
+      "type": "object",
+      "required": ["manifest", "bundle"],
+      "properties": {
+        "manifest": { "$ref": "sources-manifest.schema.json" },
+        "bundle": { "$ref": "sources-bundle.schema.json" }
+      },
+      "additionalProperties": true
+    },
+    "system": {
+      "type": "object",
+      "required": ["id", "name", "rootNodeId", "nodes", "edges"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "minLength": 1 },
+        "rootNodeId": { "$ref": "#/$defs/id" },
+        "metadata": { "type": "object", "additionalProperties": true },
+        "nodes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/node" } },
+        "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } },
+        "context": { "$ref": "#/$defs/context" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9._:-]+$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "ownership": { "enum": ["first_party", "third_party"] },
+    "node": {
+      "type": "object",
+      "required": ["id", "kind", "name", "metadata"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "kind": { "enum": ["Root", "Host", "Container", "Process", "Library"] },
+        "name": { "type": "string", "minLength": 1 },
+        "parentId": { "$ref": "#/$defs/id" },
+        "sourceSelectors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "metadata": {
+          "type": "object",
+          "required": ["ownership"],
+          "properties": {
+            "ownership": { "$ref": "#/$defs/ownership" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "type", "fromNodeId", "toNodeId"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "type": { "enum": ["Runtime", "Dataflow", "Dependency"] },
+        "fromNodeId": { "$ref": "#/$defs/id" },
+        "toNodeId": { "$ref": "#/$defs/id" },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": true
+    },
+    "document": {
+      "type": "object",
+      "required": ["kind", "hash", "title", "language", "text"],
+      "properties": {
+        "kind": { "enum": ["Document", "Skill", "Prompt"] },
+        "hash": { "$ref": "#/$defs/digest" },
+        "title": { "type": "string", "minLength": 1 },
+        "language": { "type": "string", "minLength": 1 },
+        "text": { "type": "string" },
+        "supersedes": { "$ref": "#/$defs/digest" }
+      },
+      "additionalProperties": true
+    },
+    "matrix": {
+      "type": "object",
+      "required": ["nodeId", "concern"],
+      "properties": {
+        "nodeId": { "$ref": "#/$defs/id" },
+        "concern": { "type": "string", "minLength": 1 },
+        "documentRefs": { "type": "array", "items": { "$ref": "#/$defs/digest" }, "uniqueItems": true },
+        "skillRefs": { "type": "array", "items": { "$ref": "#/$defs/digest" }, "uniqueItems": true }
+      },
+      "additionalProperties": true
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["id", "nodeId", "concern", "type"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "nodeId": { "$ref": "#/$defs/id" },
+        "concern": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["Summary", "Docs", "Code"] },
+        "language": { "type": "string" },
+        "text": { "type": "string" },
+        "sourcePaths": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      },
+      "additionalProperties": true
+    },
+    "context": {
+      "type": "object",
+      "properties": {
+        "concerns": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "documents": { "type": "array", "items": { "$ref": "#/$defs/document" } },
+        "matrix": { "type": "array", "items": { "$ref": "#/$defs/matrix" } },
+        "systemPromptRefs": { "type": "array", "items": { "$ref": "#/$defs/digest" }, "uniqueItems": true },
+        "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifact" } }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@openship/protocol",
+  "version": "0.0.1",
+  "description": "Canonical OpenShip 1.0 types, validators, consumer helpers, schemas, and skill assets.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openshipdev/openship.git",
+    "directory": "packages/protocol"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "browser": "./src/index.js",
+      "node": "./src/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./node": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./schemas/*": "./dist/skill/references/schemas/*",
+    "./skill/*": "./dist/skill/*"
+  },
+  "bin": {
+    "openship": "bin/openship.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@noble/hashes": "2.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/prepare-package.mjs",
+    "test": "node scripts/prepare-package.mjs && node --test test/*.test.mjs"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+export type OpenShipEncoding = "utf-8" | "base64";
+export type OpenShipCapability = "discovery" | "sources" | "changes" | "systems";
+export interface SourceFileMetadata { path: string; size: number; sha256: string; encoding: OpenShipEncoding; mediaType: string; type: "file" | "symlink"; target?: string; [key: string]: unknown }
+export interface SourcesManifest { openship: "1.0"; capability: "sources"; digest: string; project: { name: string; description: string; [key: string]: unknown }; totals: { files: number; bytes: number; [key: string]: unknown }; files: SourceFileMetadata[]; [key: string]: unknown }
+export interface SourcesBundle { openship: "1.0"; capability: "sources"; digest: string; files: Record<string, { encoding: OpenShipEncoding; content: string; [key: string]: unknown }>; [key: string]: unknown }
+export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; capabilities: { sources: { manifest: string; bundle: string; [key: string]: unknown }; systems?: { document: string; [key: string]: unknown }; changes?: { policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
+export type SystemsNodeKind = "Root" | "Host" | "Container" | "Process" | "Library";
+export type SystemsNodeOwnership = "first_party" | "third_party";
+export interface SystemsNodeMetadata { ownership: SystemsNodeOwnership; [key: string]: unknown }
+export interface SystemsNode { id: string; kind: SystemsNodeKind; name: string; parentId?: string; sourceSelectors?: string[]; metadata: SystemsNodeMetadata; [key: string]: unknown }
+export interface SystemsGraph { id: string; name: string; rootNodeId: string; nodes: SystemsNode[]; edges: Array<Record<string, unknown>>; metadata?: Record<string, unknown>; context?: Record<string, unknown>; [key: string]: unknown }
+export interface SystemsDocument { openship: "1.0"; capability: "systems"; source: { manifest: SourcesManifest; bundle: SourcesBundle; [key: string]: unknown }; system: SystemsGraph; [key: string]: unknown }
+export interface VerifiedSourceFile { metadata: SourceFileMetadata; bytes: Uint8Array }
+export interface VerifiedSources { manifest: SourcesManifest; bundle: SourcesBundle; files: VerifiedSourceFile[]; decodedBytes: number }
+export interface FetchedOpenShip { origin: string; discovery: DiscoveryDocument; snapshot: { kind: "systems"; document: SystemsDocument } | { kind: "sources"; manifest: SourcesManifest; bundle: SourcesBundle }; verified: VerifiedSources }
+export class OpenShipValidationError extends Error { path: string; code: string; constructor(path: string, message: string, code?: string) }
+export function sha256Hex(value: string | Uint8Array): string;
+export function decodeOpenShipBase64(value: string, path?: string): Uint8Array;
+export function encodeOpenShipBase64(value: Uint8Array): string;
+export function assertSafePath(value: unknown, path?: string): string;
+export function compareUtf8(left: string, right: string): number;
+export function matchOpenShipPattern(pattern: string, path: string): boolean;
+export function computeSourcesDigest(files: SourceFileMetadata[]): string;
+export function validateDiscovery(value: unknown): DiscoveryDocument;
+export function validateSources(manifest: unknown, bundle: unknown, options?: { maxDecodedBytes?: number }): VerifiedSources;
+export function validateSystems(value: unknown, options?: { maxDecodedBytes?: number }): SystemsDocument;
+export function validateChangesDocument(value: unknown): Record<string, unknown>;
+export function validateChangesSubmission(value: unknown): Record<string, unknown>;
+export function validateChangesAccepted(value: unknown): Record<string, unknown>;
+export function validateChangesStatus(value: unknown): Record<string, unknown>;
+export function validateChangesPolicy(value: unknown): Record<string, unknown>;
+export function validateChangesViolation(value: unknown): Record<string, unknown>;
+export function normalizeOpenShipOrigin(origin: string, options?: { allowLoopbackHttp?: boolean }): string;
+export function fetchOpenShip(origin: string, options?: { fetch?: typeof fetch; maxDecodedBytes?: number; allowLoopbackHttp?: boolean; preferSystems?: boolean }): Promise<FetchedOpenShip>;
+export function composeChangesSubmission(base: VerifiedSources, current: VerifiedSources, input: { title: string; intent: string }): Record<string, unknown>;
+export function diffSources(base: VerifiedSources, current: VerifiedSources): Array<{ path: string; operation: "create" | "replace" | "delete"; before: VerifiedSourceFile | null; after: VerifiedSourceFile | null }>;