Template package format and template.json manifest type

SPEC-109 §2 — define the site-template package format and the template.json manifest type. The config payload is a SiteConfig partial (install = add a site); the path fields are install-derived, not author-set.

main View source

Criteria completion

Relationships

ID:SPEC-109Status:accepted

Site template packages, manifest, and scaffolding

ID:WORK-465Status:done

ADR-023 manifest compatibility fields and shared refrakt-range check

Priority:highComplexity:moderateMilestone:v0.25.0

ID:WORK-453Status:done

Template apply as add-a-site: copy content, derive dirs, pin deps

Priority:highComplexity:complexMilestone:v0.25.0

ID:WORK-455Status:done

Reference template fixture and scaffold-build CI

Priority:mediumComplexity:moderateMilestone:v0.25.0

ID:WORK-464Status:done

Authoring docs for distributables (template, theme, plugin, preset-pack)

Priority:mediumComplexity:simpleMilestone:v0.25.0

main current done

changeset-release/main done claude/v0.25.0-impl done claude/v0.25.0-workitems ready

Jun 24, 06:37 AMf6e6a38
- ☑ A `template.json` type is defined: metadata (`kind`, `name`, `title`, `description`, `category`, a `refrakt` range, optional `previewUrl`) plus a `site` field that is a `SiteConfig` partial
- ☑ The `site` partial **omits** `contentDir`/`sandbox.dir` — they are install-derived ({% ref "SPEC-109" /%} §2)
- ☑ `kind` defaults to `"site"`; `"section"` is reserved (type-level only, not implemented)
- ☑ The package layout (`content/`, optional `sandboxes/`) is documented as fixed source-folder names
- ☑ The type lives in `packages/types` and is importable by the install path and the scaffold
by bjornolofandersson
Jun 23, 07:52 PMdede57e
Created (ready)by bjornolofandersson
Jun 23, 07:42 PMc36d24c
Content editedby Claude
plan(v0.25.0): renumber WORK-444 → WORK-465 to avoid collision with main
Jun 23, 07:22 PMa6bdcba
Content editedby Claude
plan(v0.25.0): accept specs/ADRs and decompose into 21 work items

Acceptance Criteria

A template.json type is defined: metadata (kind, name, title, description, category, a refrakt range, optional previewUrl) plus a site field that is a SiteConfig partial
The site partial omits contentDir/sandbox.dir — they are install-derived (SPEC-109 §2)
kind defaults to "site"; "section" is reserved (type-level only, not implemented)
The package layout (content/, optional sandboxes/) is documented as fixed source-folder names
The type lives in packages/types and is importable by the install path and the scaffold

Approach

Add the template.json interface alongside ThemeManifest in packages/types/src/theme.ts, reusing SiteConfig. No runtime yet — this is the shared shape the apply step and scaffold both consume.

Dependencies

WORK-465 — the refrakt range field

References

SPEC-109 §2; packages/types/src/theme.ts (SiteConfig)

Resolution

Completed: 2026-06-23

Branch: claude/v0.25.0-impl

What was done

Satisfied as part of the foundation (WORK-465): TemplateManifest + TemplateSiteConfig in packages/types/src/distribution.ts. Metadata (kind?, name, title, description?, category?, refrakt?, previewUrl?) + site: TemplateSiteConfig where TemplateSiteConfig = Omit<Partial<SiteConfig>, 'contentDir' | 'sandbox'> (the install-derived path fields are removed at the type level). kind is optional and documented as defaulting to "site"; "section" reserved. Package layout (content/, sandboxes/ fixed source folders) documented in the JSDoc. Exported from the types index; consumed by the CLI install path.