Skip to content

Commit b007131

Browse files
committed
docs: serve hyperframes.json / registry JSON schemas (#304)
The three /schema/*.json URLs baked into every Hyperframes project as \$schema references were all 404ing on the live docs site — blocking editor autocomplete and validation for hyperframes.json, registry.json, and registry-item.json. Adds docs/schema/ so Mintlify serves the three expected URLs: - /schema/hyperframes.json (new — authored from ProjectConfig) - /schema/registry.json (mirrored from packages/core/schemas/) - /schema/registry-item.json (mirrored from packages/core/schemas/) The registry schemas stay authoritative in packages/core/schemas/ where they're npm-exported for @hyperframes/core consumers. scripts/sync-schemas.ts mirrors them into docs/schema/ and a new --check mode fails the Docs workflow if the two drift, so the npm copy and the docs copy can't diverge silently. Validated against the factory-series-c-video config + a default config generated by hyperframes init; negative cases (missing registry, extra top-level keys, empty required strings) reject as expected.
1 parent 46afe2e commit b007131

6 files changed

Lines changed: 300 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,15 @@ on:
55
paths:
66
- "docs/**"
77
- "DOCS_GUIDELINES.md"
8+
- "packages/core/schemas/**"
9+
- "scripts/sync-schemas.ts"
810
push:
911
branches: [main]
1012
paths:
1113
- "docs/**"
1214
- "DOCS_GUIDELINES.md"
15+
- "packages/core/schemas/**"
16+
- "scripts/sync-schemas.ts"
1317

1418
concurrency:
1519
group: docs-${{ github.ref }}
@@ -27,6 +31,9 @@ jobs:
2731
with:
2832
node-version: 22
2933

34+
- name: Check schema mirror (core → docs)
35+
run: npx tsx scripts/sync-schemas.ts --check
36+
3037
- name: Validate build
3138
working-directory: docs
3239
run: npx mint validate

‎docs/schema/hyperframes.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://hyperframes.heygen.com/schema/hyperframes.json",
4+
"title": "Hyperframes Project Config",
5+
"description": "Per-project configuration for a Hyperframes project (hyperframes.json). Tells `hyperframes add` which registry to pull items from and where to drop them in the project tree. Created by `hyperframes init`; users may edit it to point at custom registries or reshape their project layout.",
6+
"type": "object",
7+
"required": ["registry", "paths"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"$schema": {
11+
"type": "string",
12+
"format": "uri",
13+
"description": "JSON Schema URL — https://hyperframes.heygen.com/schema/hyperframes.json."
14+
},
15+
"registry": {
16+
"type": "string",
17+
"format": "uri",
18+
"minLength": 1,
19+
"description": "Base URL of the registry to pull items from. Point at the official Hyperframes registry or a custom one."
20+
},
21+
"paths": {
22+
"type": "object",
23+
"description": "Target paths for each item type, relative to the project root.",
24+
"required": ["blocks", "components", "assets"],
25+
"additionalProperties": false,
26+
"properties": {
27+
"blocks": {
28+
"type": "string",
29+
"minLength": 1,
30+
"description": "Where `hyperframes:block` items land. Defaults to `compositions`."
31+
},
32+
"components": {
33+
"type": "string",
34+
"minLength": 1,
35+
"description": "Where `hyperframes:component` items land. Defaults to `compositions/components`."
36+
},
37+
"assets": {
38+
"type": "string",
39+
"minLength": 1,
40+
"description": "Where asset files (images, fonts, videos) land. Defaults to `assets`."
41+
}
42+
}
43+
}
44+
}
45+
}

‎docs/schema/registry-item.json‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://hyperframes.heygen.com/schema/registry-item.json",
4+
"title": "Hyperframes Registry Item",
5+
"description": "Manifest for a single distributable item (example, block, or component).",
6+
"type": "object",
7+
"required": ["name", "type", "title", "description", "files"],
8+
"properties": {
9+
"$schema": {
10+
"type": "string",
11+
"format": "uri"
12+
},
13+
"name": {
14+
"type": "string",
15+
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
16+
"description": "Item name in kebab-case, must start and end with alphanumeric."
17+
},
18+
"type": {
19+
"type": "string",
20+
"enum": ["hyperframes:example", "hyperframes:block", "hyperframes:component"]
21+
},
22+
"title": {
23+
"type": "string",
24+
"minLength": 1
25+
},
26+
"description": {
27+
"type": "string",
28+
"minLength": 1
29+
},
30+
"tags": {
31+
"type": "array",
32+
"items": { "type": "string", "minLength": 1 }
33+
},
34+
"author": {
35+
"type": "string",
36+
"minLength": 1
37+
},
38+
"license": {
39+
"type": "string",
40+
"minLength": 1,
41+
"description": "SPDX license identifier (e.g. \"Apache-2.0\", \"MIT\")."
42+
},
43+
"minCliVersion": {
44+
"type": "string",
45+
"pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
46+
"description": "Minimum `hyperframes` CLI version required to install this item."
47+
},
48+
"deprecated": {
49+
"type": "string",
50+
"minLength": 1,
51+
"description": "If set, the item is deprecated; the value is the reason or migration note."
52+
},
53+
"dimensions": {
54+
"type": "object",
55+
"required": ["width", "height"],
56+
"additionalProperties": false,
57+
"properties": {
58+
"width": { "type": "integer", "minimum": 1 },
59+
"height": { "type": "integer", "minimum": 1 }
60+
}
61+
},
62+
"duration": {
63+
"type": "number",
64+
"exclusiveMinimum": 0,
65+
"description": "Duration in seconds. Must be > 0."
66+
},
67+
"registryDependencies": {
68+
"type": "array",
69+
"items": {
70+
"type": "string",
71+
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
72+
}
73+
},
74+
"files": {
75+
"type": "array",
76+
"minItems": 1,
77+
"items": {
78+
"type": "object",
79+
"required": ["path", "target", "type"],
80+
"additionalProperties": false,
81+
"properties": {
82+
"path": {
83+
"type": "string",
84+
"minLength": 1,
85+
"description": "Source path, relative to registry-item.json."
86+
},
87+
"target": {
88+
"type": "string",
89+
"minLength": 1,
90+
"description": "Destination path in the user's project, relative to project root. Must not traverse outside the project (no `..` segments, no absolute paths).",
91+
"not": {
92+
"anyOf": [
93+
{ "pattern": "(^|[/\\\\])\\.\\.([/\\\\]|$)" },
94+
{ "pattern": "^[/\\\\]" },
95+
{ "pattern": "^[A-Za-z]:[/\\\\]" }
96+
]
97+
}
98+
},
99+
"type": {
100+
"type": "string",
101+
"enum": [
102+
"hyperframes:composition",
103+
"hyperframes:asset",
104+
"hyperframes:snippet",
105+
"hyperframes:style",
106+
"hyperframes:timeline"
107+
]
108+
}
109+
}
110+
}
111+
},
112+
"preview": {
113+
"type": "object",
114+
"additionalProperties": false,
115+
"properties": {
116+
"video": { "type": "string" },
117+
"poster": { "type": "string" }
118+
}
119+
},
120+
"relatedSkill": {
121+
"type": "string",
122+
"minLength": 1
123+
}
124+
},
125+
"allOf": [
126+
{
127+
"if": {
128+
"required": ["type"],
129+
"properties": { "type": { "const": "hyperframes:component" } }
130+
},
131+
"then": {
132+
"not": {
133+
"anyOf": [{ "required": ["dimensions"] }, { "required": ["duration"] }]
134+
}
135+
},
136+
"else": {
137+
"required": ["dimensions", "duration"]
138+
}
139+
}
140+
]
141+
}

‎docs/schema/registry.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://hyperframes.heygen.com/schema/registry.json",
4+
"title": "Hyperframes Registry Manifest",
5+
"description": "Top-level manifest describing all items in a Hyperframes registry.",
6+
"type": "object",
7+
"required": ["name", "homepage", "items"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"$schema": {
11+
"type": "string",
12+
"format": "uri"
13+
},
14+
"name": {
15+
"type": "string",
16+
"minLength": 1,
17+
"description": "Registry name (e.g. \"hyperframes\")."
18+
},
19+
"homepage": {
20+
"type": "string",
21+
"format": "uri",
22+
"description": "Registry homepage URL."
23+
},
24+
"items": {
25+
"type": "array",
26+
"description": "Items in this registry. Each entry is a shorthand reference; the full item manifest lives at <type-dir>/<name>/registry-item.json.",
27+
"items": {
28+
"type": "object",
29+
"required": ["name", "type"],
30+
"additionalProperties": false,
31+
"properties": {
32+
"name": {
33+
"type": "string",
34+
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
35+
"description": "Item name in kebab-case, must start and end with alphanumeric."
36+
},
37+
"type": {
38+
"type": "string",
39+
"enum": ["hyperframes:example", "hyperframes:block", "hyperframes:component"]
40+
}
41+
}
42+
}
43+
}
44+
}
45+
}

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818
"build:hyperframes-runtime:modular": "bun run --filter @hyperframes/core build:hyperframes-runtime:modular",
1919
"verify:packed-manifests": "node scripts/verify-packed-manifests.mjs",
2020
"set-version": "tsx scripts/set-version.ts",
21+
"sync-schemas": "tsx scripts/sync-schemas.ts",
22+
"sync-schemas:check": "tsx scripts/sync-schemas.ts --check",
2123
"lint": "oxlint . && tsx scripts/lint-skills.ts",
2224
"lint:skills": "tsx scripts/lint-skills.ts",
2325
"lint:fix": "oxlint --fix .",

‎scripts/sync-schemas.ts‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
#!/usr/bin/env tsx
2+
/**
3+
* Mirror JSON Schemas from `packages/core/schemas/` into `docs/schema/` so
4+
* Mintlify serves them at `https://hyperframes.heygen.com/schema/*`. The core
5+
* copies stay authoritative — they're exported from `@hyperframes/core` for
6+
* npm consumers — and this script is the single contract that prevents the
7+
* docs mirror from drifting.
8+
*
9+
* Usage:
10+
* bun run sync-schemas # copy core → docs
11+
* bun run sync-schemas --check # exit non-zero if copies are stale (CI)
12+
*
13+
* `docs/schema/hyperframes.json` is authored directly in docs (no source in
14+
* core) so it's skipped by this script.
15+
*/
16+
17+
import { readFileSync, writeFileSync } from "node:fs";
18+
import { join } from "node:path";
19+
20+
const ROOT = join(import.meta.dirname, "..");
21+
const SOURCE_DIR = join(ROOT, "packages/core/schemas");
22+
const TARGET_DIR = join(ROOT, "docs/schema");
23+
const MIRRORED = ["registry.json", "registry-item.json"];
24+
25+
function main() {
26+
const checkOnly = process.argv.includes("--check");
27+
let drift = 0;
28+
29+
for (const name of MIRRORED) {
30+
const source = readFileSync(join(SOURCE_DIR, name), "utf-8");
31+
const targetPath = join(TARGET_DIR, name);
32+
const target = (() => {
33+
try {
34+
return readFileSync(targetPath, "utf-8");
35+
} catch {
36+
return null;
37+
}
38+
})();
39+
40+
if (target === source) {
41+
console.log(` ✓ ${name} in sync`);
42+
continue;
43+
}
44+
45+
drift++;
46+
if (checkOnly) {
47+
console.error(` ✗ ${name} out of sync (run \`bun run sync-schemas\` to fix)`);
48+
continue;
49+
}
50+
writeFileSync(targetPath, source);
51+
console.log(` → ${name} updated`);
52+
}
53+
54+
if (checkOnly && drift > 0) {
55+
console.error(`\n${drift} schema${drift === 1 ? "" : "s"} drifted from source.`);
56+
process.exit(1);
57+
}
58+
}
59+
60+
main();

0 commit comments

Comments
 (0)