kitfly 0.1.2 → 0.2.0

package/schemas/plugin-schemas-notes.md

@@ -0,0 +1,71 @@
+---
+title: "Plugin Schema Notes"
+description: "Rationale and validation rules for plugin.yaml and registry/plugins.yaml schemas"
+last_updated: "2026-02-12"
+status: "draft"
+tags:
+  - plugins
+  - schemas
+  - supply-chain
+---
+
+# Plugin Schema Notes (v0.2.0)
+
+This note accompanies the draft schemas:
+
+- `schemas/plugin.schema.json` → `schemas/v0/plugin.schema.json` (plugin.yaml)
+- `schemas/plugin-registry.schema.json` → `schemas/v0/plugin-registry.schema.json` (registry/plugins.yaml)
+
+## Hook validation rules (plugin.yaml)
+
+The `hooks` block is validated as a strict object:
+
+- Allowed keys: `marked-extension`, `template-head`, `template-body-end`
+- Value type: boolean (`true`/`false`) only
+- Unknown keys: **invalid** (schema rejects via `additionalProperties: false`)
+
+Rationale: Contract-first + minimal loader. Unknown hooks should be caught at validation time rather than ignored at runtime.
+
+## Supply chain constraints
+
+- `dependencies.cdn[]` requires both `url` and `integrity`.
+- `integrity` must be an SRI string (`sha256|sha384|sha512` + base64).
+- Registry entries use **per-asset** SHA256 checksums: `assets.assetSha256.js` and/or `assets.assetSha256.css`.
+
+Rationale: The brief mandates SRI on all CDN resources; the schema encodes this as required fields, not optional hints.
+
+Rationale (checksums): Release-time `CHECKSUMS.yaml` is per-asset, and install-time verification should validate each fetched asset independently (JS and CSS can be cached and verified separately). Using an algorithm-specific field name (`assetSha256`) keeps room for future parallel algorithms without overloading a generic `checksums` structure.
+
+## Registry asset types
+
+The registry schema intentionally only supports `assets.js` and `assets.css` in v0.2.0.
+
+Rationale: Keep the contract minimal; add additional asset types only when a concrete plugin requires them.
+
+## Local registries (`baseUrl: ""`)
+
+For offline/local registries that only reference on-disk assets (e.g. `plugins-dist/...`), `baseUrl` may be an empty string.
+
+## Mode allowlisting (`modes`)
+
+Both plugin manifests (`plugin.yaml`) and registry entries may include an optional `modes` field.
+
+Semantics:
+
+- Omitted: allowed in **all** Kitfly modes
+- Present with values (e.g. `["docs"]`): allowed only in those modes
+- Present but empty (`[]`): blocked in **all** modes (useful for temporarily disabling a plugin without removing it from `kitfly.plugins.yaml`)
+
+Rationale: Kitfly has two primary rendering modes (`docs` and `slides`). Mode allowlisting is an intentionally small mechanism to keep plugins predictable and easy to dogfood across both surfaces.
+
+## Version range validation
+
+The `kitfly` field is required and validated as a simple “space-separated comparator” string (e.g. `>=0.2.0 <1.0.0`).
+
+Rationale: JSON Schema cannot fully validate npm/semver range syntax without embedding a custom parser. This pattern check is intentionally minimal: it enforces “looks like comparator(s) + semver” while leaving exact semantics to the loader.
+
+## Atomic plugins (no plugin-to-plugin dependencies)
+
+The schema defines `dependencies` with `additionalProperties: false` and only allows a `cdn` field.
+
+Rationale: This makes `dependencies.plugins` (or any other dependency category) invalid by construction, matching the “atomic plugins” decision.

package/schemas/plugin.schema.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/plugin.schema.json",
+  "$ref": "./v0/plugin.schema.json"
+}

package/schemas/plugins.schema.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/plugins.schema.json",
+  "$ref": "./v0/plugins.schema.json"
+}

package/schemas/v0/common.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/v0/common.schema.json",
+  "$version": "0.2.0",
+  "title": "Kitfly Common Schema Definitions",
+  "description": "Shared $defs used across Kitfly schemas (v0).",
+  "$defs": {
+    "kitflyMode": {
+      "type": "string",
+      "description": "Kitfly rendering mode.",
+      "enum": [
+        "docs",
+        "slides"
+      ],
+      "examples": [
+        "docs",
+        "slides"
+      ]
+    },
+    "kitflyModesAllowlist": {
+      "type": "array",
+      "description": "Optional allowlist for where a plugin may run. If omitted, plugin is allowed in all modes. If present and empty, plugin is blocked in all modes.",
+      "items": {
+        "$ref": "#/$defs/kitflyMode"
+      },
+      "uniqueItems": true
+    },
+    "semver": {
+      "type": "string",
+      "description": "Semantic version string (semver).",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+      "examples": [
+        "1.0.0",
+        "1.2.3-beta.1"
+      ]
+    },
+    "semverRange": {
+      "type": "string",
+      "description": "Version compatibility range (space-separated comparators). Example: \">=0.2.0 <1.0.0\"",
+      "minLength": 1,
+      "maxLength": 80,
+      "pattern": "^\\s*(?:[<>=~^]*\\s*)?(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:\\s+(?:[<>=~^]*\\s*)?(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*))*\\s*$",
+      "examples": [
+        ">=0.2.0 <1.0.0"
+      ]
+    },
+    "sriIntegrity": {
+      "type": "string",
+      "description": "Subresource Integrity value (sha256/sha384/sha512 base64).",
+      "pattern": "^(sha256|sha384|sha512)-[A-Za-z0-9+/=]+$",
+      "examples": [
+        "sha384-abcDEF123+/="
+      ]
+    },
+    "checksumSha256": {
+      "type": "string",
+      "description": "SHA256 checksum (hex) prefixed with sha256:",
+      "pattern": "^sha256:[0-9a-fA-F]{64}$",
+      "examples": [
+        "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+      ]
+    }
+  }
+}

package/schemas/v0/plugin-registry.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/v0/plugin-registry.schema.json",
+  "$version": "0.2.0",
+  "title": "Plugin Registry",
+  "description": "Schema for kitfly canonical plugin registry (registry/plugins.yaml).",
+  "type": "object",
+  "required": [
+    "version",
+    "updated",
+    "baseUrl",
+    "plugins"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Schema reference for validation"
+    },
+    "version": {
+      "type": "integer",
+      "description": "Registry schema version",
+      "minimum": 1,
+      "examples": [
+        1
+      ]
+    },
+    "updated": {
+      "type": "string",
+      "description": "Last update date (YYYY-MM-DD)",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "examples": [
+        "2026-02-04"
+      ]
+    },
+    "baseUrl": {
+      "type": "string",
+      "description": "Base URL used for templating plugin asset URLs via ${baseUrl}",
+      "minLength": 0,
+      "maxLength": 200,
+      "examples": [
+        "https://github.com/3leaps/kitfly/releases/download"
+      ]
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Plugin entries keyed by plugin id",
+      "minProperties": 0,
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "$ref": "#/$defs/registryPlugin"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "registryAssets": {
+      "type": "object",
+      "description": "Plugin asset URLs. Strings may include ${baseUrl} templating.",
+      "required": [
+        "assetSha256"
+      ],
+      "properties": {
+        "js": {
+          "type": "string",
+          "description": "JavaScript bundle URL (may include ${baseUrl})",
+          "minLength": 1
+        },
+        "css": {
+          "type": "string",
+          "description": "CSS bundle URL (may include ${baseUrl})",
+          "minLength": 1
+        },
+        "assetSha256": {
+          "type": "object",
+          "description": "Per-asset SHA256 checksums (sha256:<hex>) keyed by asset type.",
+          "properties": {
+            "js": {
+              "$ref": "./common.schema.json#/$defs/checksumSha256"
+            },
+            "css": {
+              "$ref": "./common.schema.json#/$defs/checksumSha256"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "anyOf": [
+            {
+              "required": [
+                "js"
+              ]
+            },
+            {
+              "required": [
+                "css"
+              ]
+            }
+          ]
+        },
+        {
+          "if": {
+            "required": [
+              "js"
+            ]
+          },
+          "then": {
+            "properties": {
+              "assetSha256": {
+                "required": [
+                  "js"
+                ]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "css"
+            ]
+          },
+          "then": {
+            "properties": {
+              "assetSha256": {
+                "required": [
+                  "css"
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "registryPlugin": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "version",
+        "contract",
+        "kitfly",
+        "license",
+        "verified",
+        "assets"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Human-readable plugin name",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "description": {
+          "type": "string",
+          "description": "Short description used in listing/help output",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "version": {
+          "$ref": "./common.schema.json#/$defs/semver"
+        },
+        "contract": {
+          "type": "string",
+          "description": "Plugin contract version this plugin implements (stringified integer)",
+          "pattern": "^[0-9]+$",
+          "examples": [
+            "1"
+          ]
+        },
+        "kitfly": {
+          "$ref": "./common.schema.json#/$defs/semverRange"
+        },
+        "license": {
+          "type": "string",
+          "description": "License identifier (typically SPDX, e.g. MIT)",
+          "minLength": 1,
+          "maxLength": 50
+        },
+        "verified": {
+          "type": "boolean",
+          "description": "If true, plugin is first-party / reviewed (canonical registry)"
+        },
+        "modes": {
+          "$ref": "./common.schema.json#/$defs/kitflyModesAllowlist"
+        },
+        "assets": {
+          "$ref": "#/$defs/registryAssets"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "$schema": "./schemas/v0/plugin-registry.schema.json",
+      "version": 1,
+      "updated": "2026-02-04",
+      "baseUrl": "https://github.com/3leaps/kitfly/releases/download",
+      "plugins": {
+        "latex": {
+          "name": "LaTeX/KaTeX Math Rendering",
+          "description": "Render LaTeX math expressions with KaTeX",
+          "version": "1.0.0",
+          "contract": "1",
+          "kitfly": ">=0.2.0 <1.0.0",
+          "license": "MIT",
+          "verified": true,
+          "assets": {
+            "js": "${baseUrl}/v1.0.0/latex.js",
+            "css": "${baseUrl}/v1.0.0/latex.css",
+            "assetSha256": {
+              "js": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+              "css": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/v0/plugin.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/v0/plugin.schema.json",
+  "$version": "0.2.0",
+  "title": "Plugin Manifest",
+  "description": "Contract for kitfly plugins (plugin.yaml). Plugins are atomic (no plugin-to-plugin dependencies).",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "contract",
+    "description",
+    "license",
+    "kitfly",
+    "main"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Schema reference for validation"
+    },
+    "name": {
+      "type": "string",
+      "description": "Plugin identifier (used as registry key and folder name)",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "maxLength": 40,
+      "examples": [
+        "latex",
+        "callouts",
+        "slides-widgets"
+      ]
+    },
+    "version": {
+      "$ref": "./common.schema.json#/$defs/semver"
+    },
+    "contract": {
+      "type": "string",
+      "description": "Plugin contract version this plugin implements (stringified integer)",
+      "pattern": "^[0-9]+$",
+      "examples": [
+        "1"
+      ]
+    },
+    "description": {
+      "type": "string",
+      "description": "Short human-readable description of the plugin",
+      "minLength": 1,
+      "maxLength": 140
+    },
+    "license": {
+      "type": "string",
+      "description": "License identifier (typically SPDX, e.g. MIT)",
+      "minLength": 1,
+      "maxLength": 50,
+      "examples": [
+        "MIT"
+      ]
+    },
+    "kitfly": {
+      "$ref": "./common.schema.json#/$defs/semverRange"
+    },
+    "dependencies": {
+      "type": "object",
+      "description": "External resources required by the plugin (plugin-to-plugin dependencies are not allowed)",
+      "properties": {
+        "cdn": {
+          "type": "array",
+          "description": "External CDN resources (SRI integrity is required for every entry)",
+          "items": {
+            "$ref": "#/$defs/cdnResource"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Hook declarations (unknown hooks are invalid)",
+      "properties": {
+        "marked-extension": {
+          "type": "boolean",
+          "description": "Plugin provides a marked extension"
+        },
+        "template-head": {
+          "type": "boolean",
+          "description": "Plugin injects content into <head>"
+        },
+        "template-body-end": {
+          "type": "boolean",
+          "description": "Plugin injects content before </body>"
+        }
+      },
+      "additionalProperties": false
+    },
+    "main": {
+      "type": "string",
+      "description": "Plugin entry point (relative path within the plugin package)",
+      "pattern": "^[^\\0]+\\.(ts|js)$",
+      "examples": [
+        "index.ts"
+      ]
+    },
+    "test-docs": {
+      "type": "array",
+      "description": "Glob patterns for validation corpus docs used in kitfly plugin testing",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "examples": [
+        [
+          "test-docs/latex-samples/*.md"
+        ]
+      ]
+    },
+    "modes": {
+      "$ref": "./common.schema.json#/$defs/kitflyModesAllowlist"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "cdnResource": {
+      "type": "object",
+      "required": [
+        "url",
+        "integrity"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "CDN URL (HTTPS required)",
+          "pattern": "^https://.+",
+          "minLength": 9
+        },
+        "integrity": {
+          "$ref": "./common.schema.json#/$defs/sriIntegrity"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "$schema": "./schemas/v0/plugin.schema.json",
+      "name": "latex",
+      "version": "1.0.0",
+      "contract": "1",
+      "description": "LaTeX/KaTeX math rendering",
+      "license": "MIT",
+      "kitfly": ">=0.2.0 <1.0.0",
+      "dependencies": {
+        "cdn": [
+          {
+            "url": "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js",
+            "integrity": "sha384-abcDEF123+/="
+          },
+          {
+            "url": "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css",
+            "integrity": "sha384-abcDEF123+/="
+          }
+        ]
+      },
+      "hooks": {
+        "marked-extension": true,
+        "template-head": true
+      },
+      "main": "index.ts",
+      "test-docs": [
+        "test-docs/latex-samples/*.md"
+      ]
+    }
+  ]
+}

package/schemas/v0/plugins.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitfly.app/schemas/v0/plugins.schema.json",
+  "$version": "0.2.0",
+  "title": "Plugin Configuration",
+  "description": "Configuration for enabling Kitfly plugins (kitfly.plugins.yaml). Canonical plugins are specified as pinned strings (name@x.y.z). Third-party plugins are objects and require explicit opt-in at build/dev time.",
+  "type": "object",
+  "required": [
+    "plugins"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Schema reference for validation"
+    },
+    "plugins": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Canonical plugin reference with strict version pinning (name@x.y.z).",
+            "pattern": "^[a-z][a-z0-9-]*@(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+            "examples": [
+              "latex@1.0.0",
+              "slides-widgets@0.2.0-beta.1"
+            ]
+          },
+          {
+            "type": "object",
+            "description": "Third-party plugin reference (requires --allow-untrusted).",
+            "required": [
+              "name",
+              "source",
+              "sha256"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Plugin identifier (used for caching and logging).",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "minLength": 1,
+                "maxLength": 40
+              },
+              "source": {
+                "type": "string",
+                "description": "Plugin source locator (e.g. github:owner/repo@ref or https://... ).",
+                "minLength": 1,
+                "maxLength": 200
+              },
+              "sha256": {
+                "type": "string",
+                "description": "Expected SHA256 checksum (hex) for the fetched plugin bundle.",
+                "pattern": "^[0-9a-fA-F]{64}$"
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "$schema": "./schemas/v0/plugins.schema.json",
+      "plugins": [
+        "latex@1.0.0",
+        "callouts@1.2.0"
+      ]
+    },
+    {
+      "$schema": "./schemas/v0/plugins.schema.json",
+      "plugins": [
+        {
+          "name": "custom-plugin",
+          "source": "github:someuser/their-plugin@v1.0.0",
+          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+        }
+      ]
+    }
+  ]
+}