@kubuild/schema 0.0.1

package/dist/index.js

@@ -0,0 +1,862 @@
+// src/document.ts
+import { z } from "zod";
+var SCHEMA_NAME = "stora.page";
+var CURRENT_SCHEMA_VERSION = "1.0.0";
+var AssetReferenceSchema = z.object({
+  type: z.literal("asset"),
+  assetId: z.string().min(1, "Asset ID cannot be empty"),
+  filename: z.string().optional(),
+  mimeType: z.string().optional(),
+  fallbackUrl: z.string().url().optional()
+});
+var VariableBindingSchema = z.object({
+  type: z.literal("variable"),
+  key: z.string().min(1, "Variable key cannot be empty"),
+  fallback: z.unknown().optional()
+});
+var ActionBindingSchema = z.object({
+  type: z.string().min(1, "Action type cannot be empty"),
+  payload: z.record(z.string(), z.unknown()).optional()
+});
+var DANGEROUS_STYLE_VALUE_PATTERN = /javascript:|expression\(|@import|<script|vbscript:|data:text\/html/i;
+var StyleValueSchema = z.union([
+  z.string().refine((value) => !DANGEROUS_STYLE_VALUE_PATTERN.test(value), {
+    message: "Style value contains a disallowed or unsafe pattern"
+  }),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.undefined()
+]);
+var StyleDefinitionSchema = z.record(z.string(), StyleValueSchema);
+var PseudoStateStylesSchema = z.record(z.string(), StyleDefinitionSchema);
+var ResponsiveStylesSchema = z.object({
+  base: StyleDefinitionSchema.optional(),
+  desktop: StyleDefinitionSchema.optional(),
+  tablet: StyleDefinitionSchema.optional(),
+  mobile: StyleDefinitionSchema.optional(),
+  states: PseudoStateStylesSchema.optional()
+}).catchall(StyleDefinitionSchema).default({});
+var NodeSchema = z.lazy(
+  () => z.object({
+    id: z.string().min(1, "Node ID must be a non-empty string"),
+    type: z.string().min(1, "Node type must be a non-empty string"),
+    props: z.record(z.string(), z.unknown()).optional().default({}),
+    styles: ResponsiveStylesSchema.optional().default({}),
+    children: z.array(NodeSchema).optional().default([])
+  })
+);
+var RootPageNodeSchema = NodeSchema.refine(
+  (node) => node.type === "page",
+  {
+    message: 'Root node must have type "page"',
+    path: ["type"]
+  }
+);
+var DocumentMetadataSchema = z.object({
+  title: z.string().min(1, "Title is required").default("Untitled Page"),
+  description: z.string().optional().default(""),
+  author: z.string().optional().default(""),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+  tags: z.array(z.string()).optional().default([]),
+  category: z.string().optional().default("general"),
+  version: z.string().optional().default("1.0.0"),
+  custom: z.record(z.string(), z.unknown()).optional()
+});
+var PageDocumentSchema = z.object({
+  schema: z.literal(SCHEMA_NAME),
+  version: z.string().min(1, "Schema version is required").default(CURRENT_SCHEMA_VERSION),
+  metadata: DocumentMetadataSchema.optional(),
+  document: RootPageNodeSchema
+});
+function isAssetReference(value) {
+  return AssetReferenceSchema.safeParse(value).success;
+}
+function isVariableBinding(value) {
+  return VariableBindingSchema.safeParse(value).success;
+}
+function isActionBinding(value) {
+  return ActionBindingSchema.safeParse(value).success;
+}
+function generateDeterministicNodeId(prefix, indexOrKey) {
+  const cleanPrefix = prefix.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+  return `${cleanPrefix}_${indexOrKey}`;
+}
+function collectNodeIds(node) {
+  const ids = [node.id];
+  if (node.children && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      ids.push(...collectNodeIds(child));
+    }
+  }
+  return ids;
+}
+function validateNodeIdUniqueness(node) {
+  const allIds = collectNodeIds(node);
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const id of allIds) {
+    if (seen.has(id)) {
+      duplicates.add(id);
+    } else {
+      seen.add(id);
+    }
+  }
+  return {
+    valid: duplicates.size === 0,
+    duplicateIds: Array.from(duplicates)
+  };
+}
+
+// src/manifest.ts
+import { z as z2 } from "zod";
+var ManifestAssetItemSchema = z2.object({
+  id: z2.string().min(1, "Asset ID cannot be empty"),
+  path: z2.string().min(1, "Asset archive path cannot be empty"),
+  mimeType: z2.string().min(1, "MIME type cannot be empty"),
+  size: z2.number().nonnegative("Asset size must be non-negative"),
+  checksum: z2.string().optional()
+});
+var ManifestSchema = z2.object({
+  schema: z2.literal(SCHEMA_NAME).default(SCHEMA_NAME),
+  schemaVersion: z2.string().min(1, "Schema version cannot be empty").default("1.0.0"),
+  packageVersion: z2.string().min(1, "Package version cannot be empty").default("1.0.0"),
+  builderCompatibility: z2.string().default(">=0.1.0"),
+  requiredComponents: z2.array(z2.string()).default([]),
+  requiredCapabilities: z2.array(z2.string()).default([]),
+  assets: z2.array(ManifestAssetItemSchema).default([]),
+  createdAt: z2.string().optional()
+});
+function isManifest(value) {
+  return ManifestSchema.safeParse(value).success;
+}
+
+// src/template.ts
+import { z as z3 } from "zod";
+var DANGEROUS_URI_PATTERN = /^(javascript:|vbscript:|data:(?!image\/))|<script/i;
+function isSafeThumbnailUrl(url) {
+  if (!url || typeof url !== "string") return false;
+  const trimmed = url.trim();
+  if (trimmed.length === 0) return false;
+  if (DANGEROUS_URI_PATTERN.test(trimmed)) return false;
+  return true;
+}
+var SafeThumbnailUrlSchema = z3.string().min(1, "Thumbnail URL cannot be empty").refine(
+  (url) => isSafeThumbnailUrl(url),
+  { message: "Thumbnail URL contains an unsafe protocol or payload" }
+);
+var SafeThumbnailObjectSchema = z3.object({
+  url: SafeThumbnailUrlSchema,
+  alt: z3.string().optional(),
+  width: z3.number().positive().optional(),
+  height: z3.number().positive().optional()
+});
+var SafeThumbnailSchema = z3.union([
+  AssetReferenceSchema,
+  SafeThumbnailObjectSchema,
+  SafeThumbnailUrlSchema
+]);
+var TemplatePackageRefSchema = z3.object({
+  path: z3.string().optional(),
+  url: SafeThumbnailUrlSchema.optional(),
+  checksum: z3.string().optional(),
+  format: z3.enum(["stora", "json"]).default("stora")
+});
+var TemplateRequirementsSchema = z3.object({
+  requiredComponents: z3.array(z3.string()).default([]),
+  requiredCapabilities: z3.array(z3.string()).default([])
+});
+var TemplateRecordSchema = z3.object({
+  id: z3.string().min(1, "Template ID must be a non-empty string"),
+  name: z3.string().min(1, "Template name must be a non-empty string"),
+  description: z3.string().optional().default(""),
+  category: z3.string().optional().default("general"),
+  tags: z3.array(z3.string()).optional().default([]),
+  thumbnail: SafeThumbnailSchema.optional(),
+  author: z3.string().optional().default(""),
+  version: z3.string().optional().default("1.0.0"),
+  document: PageDocumentSchema.optional(),
+  packageReference: TemplatePackageRefSchema.optional(),
+  requirements: TemplateRequirementsSchema.default({
+    requiredComponents: [],
+    requiredCapabilities: []
+  }),
+  createdAt: z3.string().optional(),
+  updatedAt: z3.string().optional(),
+  custom: z3.record(z3.string(), z3.unknown()).optional()
+});
+function isTemplateRecord(value) {
+  return TemplateRecordSchema.safeParse(value).success;
+}
+function isSafeThumbnail(value) {
+  return SafeThumbnailSchema.safeParse(value).success;
+}
+
+// src/fixtures/starter-page.json
+var starter_page_default = {
+  schema: "stora.page",
+  version: "1.0.0",
+  metadata: {
+    title: "Welcome to KUBUILD",
+    description: "A starter template built with KUBUILD portable web builder",
+    author: "KUBUILD Team",
+    tags: ["landing-page", "starter", "portable"],
+    category: "landing",
+    version: "1.0.0",
+    createdAt: "2026-08-22T00:00:00.000Z",
+    updatedAt: "2026-08-22T00:00:00.000Z"
+  },
+  document: {
+    id: "root-page",
+    type: "page",
+    props: {
+      title: "KUBUILD Starter Page"
+    },
+    styles: {
+      base: {
+        backgroundColor: "#ffffff",
+        fontFamily: "Inter, sans-serif",
+        color: "#111827",
+        minHeight: "100vh"
+      }
+    },
+    children: [
+      {
+        id: "hero-section",
+        type: "section",
+        props: {},
+        styles: {
+          base: {
+            paddingTop: "64px",
+            paddingBottom: "64px",
+            paddingLeft: "24px",
+            paddingRight: "24px",
+            backgroundColor: "#f8fafc"
+          }
+        },
+        children: [
+          {
+            id: "hero-container",
+            type: "container",
+            props: {
+              maxWidth: "1200px"
+            },
+            styles: {
+              base: {
+                margin: "0 auto",
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                textAlign: "center",
+                gap: "24px"
+              }
+            },
+            children: [
+              {
+                id: "hero-heading",
+                type: "heading",
+                props: {
+                  text: "Build Once, Render Anywhere",
+                  level: 1
+                },
+                styles: {
+                  base: {
+                    fontSize: "48px",
+                    fontWeight: "800",
+                    color: "#0f172a",
+                    lineHeight: "1.2"
+                  },
+                  mobile: {
+                    fontSize: "32px"
+                  }
+                },
+                children: []
+              },
+              {
+                id: "hero-text",
+                type: "text",
+                props: {
+                  content: "KUBUILD is an open, portable web page builder engine designed for modern web applications."
+                },
+                styles: {
+                  base: {
+                    fontSize: "18px",
+                    color: "#475569",
+                    maxWidth: "680px",
+                    lineHeight: "1.6"
+                  }
+                },
+                children: []
+              },
+              {
+                id: "hero-image",
+                type: "image",
+                props: {
+                  src: "https://picsum.photos/200/300",
+                  asset: {
+                    type: "asset",
+                    assetId: "asset_hero_graphic",
+                    filename: "hero.webp",
+                    mimeType: "image/webp"
+                  },
+                  alt: "KUBUILD Platform Graphic",
+                  width: 640,
+                  height: 360
+                },
+                styles: {
+                  base: {
+                    borderRadius: "12px",
+                    maxWidth: "100%",
+                    height: "auto",
+                    boxShadow: "0 20px 25px -5px rgba(0, 0, 0, 0.1)"
+                  }
+                },
+                children: []
+              },
+              {
+                id: "hero-button",
+                type: "button",
+                props: {
+                  label: "Get Started",
+                  action: {
+                    type: "navigate",
+                    payload: {
+                      url: "/docs"
+                    }
+                  }
+                },
+                styles: {
+                  base: {
+                    backgroundColor: "#2563eb",
+                    color: "#ffffff",
+                    paddingTop: "12px",
+                    paddingBottom: "12px",
+                    paddingLeft: "28px",
+                    paddingRight: "28px",
+                    borderRadius: "8px",
+                    fontWeight: "600",
+                    fontSize: "16px",
+                    cursor: "pointer",
+                    border: "none"
+                  }
+                },
+                children: []
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+};
+
+// src/fixtures.ts
+var starterPageFixture = starter_page_default;
+
+// src/json-schema.ts
+var PAGE_DOCUMENT_JSON_SCHEMA_V1 = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://schema.stora.page/v1/page.json",
+  title: "StoraPageDocument",
+  description: "Portable Web Page Document v1 schema definition for KUBUILD",
+  type: "object",
+  required: ["schema", "version", "document"],
+  additionalProperties: false,
+  properties: {
+    schema: {
+      type: "string",
+      const: "stora.page",
+      description: "Identifies the document type format"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+(\\.\\d+)*$",
+      description: "Schema version of the document",
+      default: "1.0.0"
+    },
+    metadata: {
+      $ref: "#/definitions/documentMetadata"
+    },
+    document: {
+      $ref: "#/definitions/rootPageNode"
+    }
+  },
+  definitions: {
+    styleValue: {
+      type: ["string", "number", "boolean", "null"],
+      description: "A CSS property or design token value"
+    },
+    styleDefinition: {
+      type: "object",
+      additionalProperties: {
+        $ref: "#/definitions/styleValue"
+      },
+      description: "Key-value map of style properties"
+    },
+    responsiveStyles: {
+      type: "object",
+      properties: {
+        base: { $ref: "#/definitions/styleDefinition" },
+        desktop: { $ref: "#/definitions/styleDefinition" },
+        tablet: { $ref: "#/definitions/styleDefinition" },
+        mobile: { $ref: "#/definitions/styleDefinition" }
+      },
+      additionalProperties: {
+        $ref: "#/definitions/styleDefinition"
+      }
+    },
+    assetReference: {
+      type: "object",
+      required: ["type", "assetId"],
+      properties: {
+        type: {
+          type: "string",
+          const: "asset"
+        },
+        assetId: {
+          type: "string",
+          minLength: 1
+        },
+        filename: {
+          type: "string"
+        },
+        mimeType: {
+          type: "string"
+        },
+        fallbackUrl: {
+          type: "string",
+          format: "uri"
+        }
+      },
+      additionalProperties: false
+    },
+    variableBinding: {
+      type: "object",
+      required: ["type", "key"],
+      properties: {
+        type: {
+          type: "string",
+          const: "variable"
+        },
+        key: {
+          type: "string",
+          minLength: 1
+        },
+        fallback: {}
+      },
+      additionalProperties: false
+    },
+    actionBinding: {
+      type: "object",
+      required: ["type"],
+      properties: {
+        type: {
+          type: "string",
+          minLength: 1
+        },
+        payload: {
+          type: "object"
+        }
+      },
+      additionalProperties: false
+    },
+    node: {
+      type: "object",
+      required: ["id", "type"],
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Unique deterministic node identifier"
+        },
+        type: {
+          type: "string",
+          minLength: 1,
+          description: "Component type identifier"
+        },
+        props: {
+          type: "object",
+          description: "Component props payload and bindings",
+          default: {}
+        },
+        styles: {
+          $ref: "#/definitions/responsiveStyles"
+        },
+        children: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/node"
+          },
+          default: []
+        }
+      },
+      additionalProperties: false
+    },
+    rootPageNode: {
+      allOf: [
+        { $ref: "#/definitions/node" },
+        {
+          type: "object",
+          properties: {
+            type: {
+              type: "string",
+              const: "page",
+              description: 'The root node type must be "page"'
+            }
+          }
+        }
+      ]
+    },
+    documentMetadata: {
+      type: "object",
+      required: ["title"],
+      properties: {
+        title: {
+          type: "string",
+          minLength: 1,
+          default: "Untitled Page"
+        },
+        description: {
+          type: "string",
+          default: ""
+        },
+        author: {
+          type: "string",
+          default: ""
+        },
+        createdAt: {
+          type: "string",
+          format: "date-time"
+        },
+        updatedAt: {
+          type: "string",
+          format: "date-time"
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          default: []
+        },
+        category: {
+          type: "string",
+          default: "general"
+        },
+        version: {
+          type: "string",
+          default: "1.0.0"
+        },
+        custom: {
+          type: "object"
+        }
+      },
+      additionalProperties: false
+    }
+  }
+};
+function getPageDocumentJsonSchema() {
+  return PAGE_DOCUMENT_JSON_SCHEMA_V1;
+}
+var MANIFEST_JSON_SCHEMA_V1 = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://schema.stora.page/v1/manifest.json",
+  title: "StoraPackageManifest",
+  description: "Portable Package Manifest v1 schema definition for KUBUILD (.stora)",
+  type: "object",
+  required: ["schemaVersion", "packageVersion", "builderCompatibility", "requiredComponents", "requiredCapabilities", "assets"],
+  additionalProperties: false,
+  properties: {
+    schema: {
+      type: "string",
+      const: "stora.page",
+      description: "Schema identifier",
+      default: "stora.page"
+    },
+    schemaVersion: {
+      type: "string",
+      pattern: "^\\d+(\\.\\d+)*$",
+      description: "Document schema version",
+      default: "1.0.0"
+    },
+    packageVersion: {
+      type: "string",
+      pattern: "^\\d+(\\.\\d+)*$",
+      description: "Package version",
+      default: "1.0.0"
+    },
+    builderCompatibility: {
+      type: "string",
+      description: "Minimum or range of builder versions compatible with this package",
+      default: ">=0.1.0"
+    },
+    requiredComponents: {
+      type: "array",
+      items: { type: "string" },
+      description: "List of custom component types required by the page",
+      default: []
+    },
+    requiredCapabilities: {
+      type: "array",
+      items: { type: "string" },
+      description: "List of capabilities required by components in the page",
+      default: []
+    },
+    assets: {
+      type: "array",
+      items: { $ref: "#/definitions/manifestAssetItem" },
+      description: "Inventory of local assets packaged within the archive",
+      default: []
+    },
+    createdAt: {
+      type: "string",
+      format: "date-time",
+      description: "ISO timestamp when the package was created"
+    }
+  },
+  definitions: {
+    manifestAssetItem: {
+      type: "object",
+      required: ["id", "path", "mimeType", "size"],
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Unique asset identifier"
+        },
+        path: {
+          type: "string",
+          minLength: 1,
+          description: "Relative archive path to asset file (e.g. assets/hero.png)"
+        },
+        mimeType: {
+          type: "string",
+          minLength: 1,
+          description: "MIME type of the asset"
+        },
+        size: {
+          type: "number",
+          minimum: 0,
+          description: "Asset size in bytes"
+        },
+        checksum: {
+          type: "string",
+          description: "SHA-256 or algorithm-prefixed checksum (e.g. sha256:...)"
+        }
+      },
+      additionalProperties: false
+    }
+  }
+};
+function getManifestJsonSchema() {
+  return MANIFEST_JSON_SCHEMA_V1;
+}
+var TEMPLATE_RECORD_JSON_SCHEMA_V1 = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://schema.stora.page/v1/template.json",
+  title: "StoraTemplateRecord",
+  description: "Reusable Page Template Record v1 schema definition for KUBUILD",
+  type: "object",
+  required: ["id", "name"],
+  additionalProperties: false,
+  properties: {
+    id: {
+      type: "string",
+      minLength: 1,
+      description: "Unique template identifier"
+    },
+    name: {
+      type: "string",
+      minLength: 1,
+      description: "Human-readable name of the template"
+    },
+    description: {
+      type: "string",
+      default: "",
+      description: "Detailed description of the template purpose and contents"
+    },
+    category: {
+      type: "string",
+      default: "general",
+      description: "Template category grouping"
+    },
+    tags: {
+      type: "array",
+      items: { type: "string" },
+      default: [],
+      description: "Search and filter tags"
+    },
+    thumbnail: {
+      oneOf: [
+        { $ref: "#/definitions/assetReference" },
+        { $ref: "#/definitions/safeThumbnailObject" },
+        { type: "string", minLength: 1 }
+      ],
+      description: "Safe preview image asset reference or URL"
+    },
+    author: {
+      type: "string",
+      default: "",
+      description: "Template creator or team"
+    },
+    version: {
+      type: "string",
+      default: "1.0.0",
+      description: "Semantic version of the template"
+    },
+    document: {
+      $ref: "https://schema.stora.page/v1/page.json#",
+      description: "Embedded PageDocument snapshot (optional if packageReference provided)"
+    },
+    packageReference: {
+      $ref: "#/definitions/templatePackageRef",
+      description: "External package/archive reference (optional if document provided)"
+    },
+    requirements: {
+      $ref: "#/definitions/templateRequirements",
+      description: "Component and capability requirements for this template"
+    },
+    createdAt: {
+      type: "string",
+      format: "date-time",
+      description: "ISO creation timestamp"
+    },
+    updatedAt: {
+      type: "string",
+      format: "date-time",
+      description: "ISO last updated timestamp"
+    },
+    custom: {
+      type: "object",
+      description: "Custom host-specific serializable metadata"
+    }
+  },
+  definitions: {
+    assetReference: {
+      type: "object",
+      required: ["type", "assetId"],
+      properties: {
+        type: {
+          type: "string",
+          const: "asset"
+        },
+        assetId: {
+          type: "string",
+          minLength: 1
+        },
+        filename: {
+          type: "string"
+        },
+        mimeType: {
+          type: "string"
+        },
+        fallbackUrl: {
+          type: "string",
+          format: "uri"
+        }
+      },
+      additionalProperties: false
+    },
+    safeThumbnailObject: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: {
+          type: "string",
+          minLength: 1
+        },
+        alt: {
+          type: "string"
+        },
+        width: {
+          type: "number",
+          minimum: 1
+        },
+        height: {
+          type: "number",
+          minimum: 1
+        }
+      },
+      additionalProperties: false
+    },
+    templatePackageRef: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string"
+        },
+        url: {
+          type: "string"
+        },
+        checksum: {
+          type: "string"
+        },
+        format: {
+          type: "string",
+          enum: ["stora", "json"],
+          default: "stora"
+        }
+      },
+      additionalProperties: false
+    },
+    templateRequirements: {
+      type: "object",
+      properties: {
+        requiredComponents: {
+          type: "array",
+          items: { type: "string" },
+          default: []
+        },
+        requiredCapabilities: {
+          type: "array",
+          items: { type: "string" },
+          default: []
+        }
+      },
+      additionalProperties: false
+    }
+  }
+};
+function getTemplateRecordJsonSchema() {
+  return TEMPLATE_RECORD_JSON_SCHEMA_V1;
+}
+export {
+  ActionBindingSchema,
+  AssetReferenceSchema,
+  CURRENT_SCHEMA_VERSION,
+  DocumentMetadataSchema,
+  MANIFEST_JSON_SCHEMA_V1,
+  ManifestAssetItemSchema,
+  ManifestSchema,
+  NodeSchema,
+  PAGE_DOCUMENT_JSON_SCHEMA_V1,
+  PageDocumentSchema,
+  PseudoStateStylesSchema,
+  ResponsiveStylesSchema,
+  RootPageNodeSchema,
+  SCHEMA_NAME,
+  SafeThumbnailObjectSchema,
+  SafeThumbnailSchema,
+  SafeThumbnailUrlSchema,
+  StyleDefinitionSchema,
+  StyleValueSchema,
+  TEMPLATE_RECORD_JSON_SCHEMA_V1,
+  TemplatePackageRefSchema,
+  TemplateRecordSchema,
+  TemplateRequirementsSchema,
+  VariableBindingSchema,
+  collectNodeIds,
+  generateDeterministicNodeId,
+  getManifestJsonSchema,
+  getPageDocumentJsonSchema,
+  getTemplateRecordJsonSchema,
+  isActionBinding,
+  isAssetReference,
+  isManifest,
+  isSafeThumbnail,
+  isSafeThumbnailUrl,
+  isTemplateRecord,
+  isVariableBinding,
+  starterPageFixture,
+  validateNodeIdUniqueness
+};
+//# sourceMappingURL=index.js.map