kind-keyed install apply with framework-aware and compat validation

SPEC-110 §4–§5 + ADR-023/ADR-024 — unify the apply step over the shared resolver, keyed on artifact + manifest kind, and harden post-install validation (framework-aware + compat-range).

claude/v0.25.0-impl View source

Criteria completion

Tracking started Jun 23 — check back for trends.

Relationships

ID:SPEC-110Status:accepted

Theme and template install robustness

ID:ADR-023Status:accepted

Versioning and compatibility for distributed extensions

Date:2026-06-18

ID:ADR-024Status:accepted

Themes are framework-agnostic by default; the framework component layer is opt-in

ID:WORK-465Status:done

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

Priority:highComplexity:moderateMilestone:v0.25.0

ID:WORK-445Status:done

Shared install resolver: tarball name, registry passthrough, source-type detection

Priority:highComplexity:moderateMilestone:v0.25.0

ID:WORK-446Status:done

Multi-site --site targeting and config read/write helpers

Priority:highComplexity:moderateMilestone:v0.25.0

claude/v0.25.0-impl current in-progress

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

Jun 23, 08:17 PMda9667d
Created (in-progress)by bjornolofandersson
Jun 23, 08:05 PMf2c6cb8
Content editedby Claude
feat(cli): shared install resolver, multi-site --site, framework-aware v
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

Install applies a kind-keyed step over the shared resolver: theme → dependency + point the selected site's theme; kind:"site" template → add a site; preset pack → dependency + validate + optional presets.json append
kind:"section" is reserved/forward-compatible (reuses the resolver, SiteConfig merge, and --site plumbing) but out of scope
Post-install validation covers a theme's exports and a template's template.json; theme validation is framework-aware per ADR-024 (./transform required, a framework export like ./svelte optional — its absence is not warned)
Install validates each distributable's refrakt range against the project version, failing with a clear message on mismatch

Approach

Factor the apply step as a switch on artifact/kind in packages/cli/src/commands/theme.ts (rename/extend toward a general install command). Replace the current "./svelte missing → warn" check with the framework-aware rule. Call the ADR-023 compat checker before applying. The theme, template, and preset apply-modes are implemented in their respective work items; this item owns the dispatch + validation layer.

Dependencies

WORK-465 — compat range checker
WORK-445 — shared resolver
WORK-446 — multi-site --site + config helpers

References

SPEC-110 §4, §5; ADR-023; ADR-024