100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
|
# Live Artifact Schema Reference
|
||
|
|
|
||
|
|
Live artifacts are stored as daemon-owned project files under `.live-artifacts/<artifactId>/`. Agents author the source files, then register them through daemon tooling. The daemon assigns IDs, project scope, timestamps, run scope, and refresh status.
|
||
|
|
|
||
|
|
## Source files
|
||
|
|
|
||
|
|
| File | Owner | Purpose |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| `artifact.json` | agent-authored input, daemon-validated | Artifact metadata, preview settings, document metadata, and source descriptors. Must not contain daemon-owned fields. |
|
||
|
|
| `template.html` | agent-authored | `html_template_v1` template used to render the preview. |
|
||
|
|
| `data.json` | agent-authored then refresh-runner-updated | Canonical preview data. API `document.dataJson` is only a derived cache. |
|
||
|
|
| `provenance.json` | agent-authored then refresh-runner-updated | Source summary and generation notes. |
|
||
|
|
| `index.html` | daemon-derived | Generated preview output. Do not treat as source of truth. |
|
||
|
|
|
||
|
|
## Create/update input
|
||
|
|
|
||
|
|
`artifact.json` should match `LiveArtifactCreateInput` or `LiveArtifactUpdateInput` from `packages/contracts/src/api/live-artifacts.ts`.
|
||
|
|
|
||
|
|
Allowed agent-owned top-level fields:
|
||
|
|
|
||
|
|
- `title`
|
||
|
|
- `slug`
|
||
|
|
- `sessionId`
|
||
|
|
- `pinned`
|
||
|
|
- `status`
|
||
|
|
- `preview`
|
||
|
|
- `document`
|
||
|
|
|
||
|
|
Daemon-owned fields are rejected in agent input:
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `projectId`
|
||
|
|
- `createdAt`
|
||
|
|
- `updatedAt`
|
||
|
|
- `createdByRunId`
|
||
|
|
- `schemaVersion`
|
||
|
|
- `refreshStatus`
|
||
|
|
- `lastRefreshedAt`
|
||
|
|
|
||
|
|
## HTML document contract
|
||
|
|
|
||
|
|
MVP documents use `html_template_v1`:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"format": "html_template_v1",
|
||
|
|
"templatePath": "template.html",
|
||
|
|
"generatedPreviewPath": "index.html",
|
||
|
|
"dataPath": "data.json",
|
||
|
|
"dataJson": {}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
`template.html + data.json` is rendered by the daemon into `index.html` and the preview route.
|
||
|
|
|
||
|
|
### Binding rules
|
||
|
|
|
||
|
|
- Use escaped interpolation: `{{data.path.to.value}}`.
|
||
|
|
- Paths must start with `data` and use dot-separated keys; numeric array indexes are allowed as path segments.
|
||
|
|
- Supported structural directive: `data-od-repeat="item in data.items"` for one-level array repeats.
|
||
|
|
- Nested repeats, conditionals, filters, helper functions, partials, and expression evaluation are not supported.
|
||
|
|
- Raw HTML insertion is forbidden: no triple braces, ampersand interpolation, `data-od-html`, `data-od-raw`, or equivalent.
|
||
|
|
- Interpolation in text and ordinary attributes is HTML-escaped by default.
|
||
|
|
- Do not interpolate inside tag names, attribute names, comments, `<script>`, `<style>`, `<iframe srcdoc>`, event-handler attributes, or unsupported URL-bearing attributes.
|
||
|
|
|
||
|
|
## Bounded JSON limits
|
||
|
|
|
||
|
|
All persisted JSON values must fit the shared bounded JSON envelope:
|
||
|
|
|
||
|
|
| Limit | Value |
|
||
|
|
| --- | ---: |
|
||
|
|
| Maximum object/array depth | 8 |
|
||
|
|
| Maximum keys per object | 100 |
|
||
|
|
| Maximum array length | 500 |
|
||
|
|
| Maximum string length | 16 KiB |
|
||
|
|
| Maximum serialized JSON size | 256 KiB |
|
||
|
|
|
||
|
|
Forbidden keys anywhere in persisted JSON include `raw`, `rawResponse`, `payload`, `body`, `headers`, `cookie`, `authorization`, `token`, `secret`, `credential`, and `password`.
|
||
|
|
|
||
|
|
## Minimal static artifact input
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"title": "Release Status",
|
||
|
|
"preview": { "type": "html", "entry": "index.html" },
|
||
|
|
"document": {
|
||
|
|
"format": "html_template_v1",
|
||
|
|
"templatePath": "template.html",
|
||
|
|
"generatedPreviewPath": "index.html",
|
||
|
|
"dataPath": "data.json",
|
||
|
|
"dataJson": {
|
||
|
|
"summary": {
|
||
|
|
"title": "Release Status",
|
||
|
|
"status": "On track"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|