WORK-461
ID:WORK-461Status:done

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).

Priority:highComplexity:moderateMilestone:v0.25.0Source:SPEC-110
main View source

Criteria completion

Criteria completion: 4 of 4 (100%) checked; history from Jun 23 to Jun 240%25%50%75%100%Jun 23Jun 24

Relationships

Implements 1
Related 5
Branches 4
main current done
changeset-release/main doneclaude/v0.25.0-impl-3 doneclaude/v0.25.0-impl in-progressclaude/v0.25.0-workitems ready
History 5
  1. ac87cf4
    • ☑ 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
    by bjornolofandersson
  2. f6e6a38
    • ☑ `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 {% ref "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
    by bjornolofandersson
  3. dede57e
    Created (ready)by bjornolofandersson
  4. c36d24c
    Content editedby Claude
    plan(v0.25.0): renumber WORK-444 → WORK-465 to avoid collision with main
  5. a6bdcba
    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

Resolution

Completed: 2026-06-24

Branch: claude/v0.25.0-impl-3 (validation/theme/preset parts on the earlier slices).

What was done

The kind-keyed install apply is complete across the CLI:

  • theme → add dependency + point the selected site's theme (+ framework-aware export validation, ADR-024) — theme.ts (earlier slice).
  • preset pack → add dependency + validate presets.json + optional theme.presets append — presets.ts (earlier slice).
  • template kind:"site" → add a site: packages/cli/src/commands/template.ts templateInstallCommand + applyTemplateSite — resolves a local template directory, resolveTargetSite('new') (collision errors), createSite (singular→plural migration), derives contentDir (sites/<key>/content), copies content/ (+ sandboxes/ → sandbox.dir), merges the manifest site config, and pins+installs derived deps. Wired as refrakt template install <dir> [--site]. 2 tests.
  • kind:"section" reserved; refrakt compat range validated at install for every artifact (ADR-023).

Notes

  • v1 template install resolves a local directory (the portable, testable case). Tarball/registry templates are scaffold-copied artifacts — create-refrakt --template is the greenfield path; extending template install to fetch+extract those reuses the shared resolver and is a forward-compatible follow-up.