@fluid-app/fluid-cli-theme-dev 0.1.25 → 0.1.26

package/dist/skills/template-stylesheet-to-asset-migration/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: template-stylesheet-to-asset-migration
+description: |
+  Migrates per-template `styles.css` files in a local Fluid theme repo to theme-level
+  assets (`assets/*.css`) referenced explicitly from each template's `index.liquid`. Use
+  when a `fluid theme push` warned that `styles.css` files were skipped because their
+  remote template is `stylesheet_tag_injected`, when a `fluid theme push` failed with 422
+  because the backing company has `STYLESHEET_STRICT_INPUT` on, or when the user is
+  proactively bringing an older theme repo onto the new asset-based stylesheet shape.
+  The skill walks the repo one template at a time — moves the CSS bytes, chooses inline
+  vs external emission based on size, updates `index.liquid`, and pushes. Never pushes
+  without explicit approval.
+---
+
+# Template Stylesheet → Theme-Level Asset Migration
+
+## Why this migration exists
+
+Fluid used to inject each template's `stylesheet` column into the rendered HTML as an inline `<style>` block on every request. That bloated HTML, defeated browser and CDN caching, and made stylesheets impossible to author independently of Liquid. The new model:
+
+- Each template's CSS lives in a **theme-level `FileResource`** — a real asset under `assets/` in the theme repo, cacheable, editable independently.
+- The template's `index.liquid` **explicitly references** the asset via a Liquid tag:
+
+  ```liquid
+  {{ 'template-<themeable_type>-<name>.css' | asset_url | stylesheet_tag }}
+  ```
+
+- Once a template has been migrated (backend marker `stylesheet_tag_injected: true`), the CLI **skips** any local `<themeable_type>/<name>/styles.css` on push and prints a warning listing the skipped files. Under the `STYLESHEET_STRICT_INPUT` company feature flag, the API also rejects the field with 422 for any caller that still sends it.
+
+The migration is one-way: legacy `styles.css` → asset. Once the flag flips on for a company, legacy `styles.css` pushes just fail.
+
+## When to use this skill
+
+- `fluid theme push` printed a "Skipped N per-template styles.css file(s)…" warning — the remote templates are already migrated and the local files are dead weight.
+- `fluid theme push` returned 422 with "The `stylesheet` field is no longer accepted" — the company has `STYLESHEET_STRICT_INPUT` on and the remote template hasn't been migrated locally yet.
+- The user is bringing a theme repo from before the migration and wants to prep it for the new shape.
+- The user is packaging a `.zip` for import and the target company is flagged.
+
+**Do not use** when the theme is entirely made of `layouts/`, `locales/`, `config/`, or `mysite/` templates — those never had per-template stylesheets. Only `<themeable_type>/<name>/styles.css` files are in scope.
+
+## Boundaries
+
+- Every mutation is a **local file edit**. This skill never pushes, never calls the API, never asks whether to push. When the sweep finishes, hand the repo back to the user.
+- Preserve the CSS bytes exactly (byte-for-byte) — this migration is a **reshape**, not a rewrite. Refactoring CSS is a separate concern.
+- Don't touch mysite templates. Their render path is different and they still use the column.
+
+## Workflow
+
+Work one template at a time. For each `<themeable_type>/<name>/styles.css` under the theme root:
+
+1. **Read** the two files that make up the migration source:
+   - `<themeable_type>/<name>/index.liquid` — needs the Liquid reference prepended.
+   - `<themeable_type>/<name>/styles.css` — the CSS bytes to move.
+2. **Decide** how to reference the CSS (inline vs external — see the "Choosing emission" section).
+3. **Move** the CSS bytes into `assets/` under a deterministic name.
+4. **Update** `index.liquid` — insert the Liquid tag at the **top** of the file (see "Placement" below).
+5. **Delete** the old `<themeable_type>/<name>/styles.css`.
+6. **Validate** with `fluid theme lint --json` — parse the JSON, fix what it flags, re-run until clean.
+7. **Preview** — if a local dev server is running (`fluid theme dev`), reload the corresponding page and visually confirm the stylesheet still applies.
+
+Sweep through every `<themeable_type>/<name>/styles.css` in the repo. When they're all migrated, hand back to the user. Pushing / verifying / deploying is out of scope for this skill — it only reshapes the local files.
+
+## Filename convention
+
+Local files have no template ids — those exist only on the remote. Pick a short kebab-case name that mirrors the template's folder path so the intent is obvious to whoever reads the theme next:
+
+```
+template-<themeable_type>-<name>.css
+```
+
+- `<themeable_type>`: singular type folder name — `product`, `sections`, `page`, etc.
+- `<name>`: template folder name — `default`, `hero`, whatever the folder is called under the type folder.
+
+Any short, unambiguous filename works. The reference in `index.liquid` is the only pointer, so it can be renamed later without breaking anything else. Just make sure two different templates don't collide on the same asset name.
+
+## Choosing emission — external vs inline
+
+The backend's own auto-migration used a **2 KB threshold**:
+
+- **≤ 2 KB CSS** → inline via `inline_asset_content` (renders as `<style>…</style>` at request time). Keeps critical single-component CSS fast without an extra HTTP round trip.
+- **&gt; 2 KB CSS** → external via `asset_url | stylesheet_tag` (renders as `<link rel="stylesheet" href="…">`). Cacheable by browser and CDN.
+
+Use the same threshold for consistency with existing migrated templates. Check the size with `wc -c < path/to/styles.css` (bytes).
+
+### External `<link>` (default for larger CSS)
+
+```liquid
+{{ 'template-product-default.css' | asset_url | stylesheet_tag }}
+
+<div class="product">
+  <!-- template body -->
+</div>
+
+{% schema %}
+{ "name": "Product" }
+{% endschema %}
+```
+
+### Inline `<style>` (small critical CSS)
+
+```liquid
+{{ 'template-product-default.css' | inline_asset_content }}
+
+<div class="product">
+  <!-- template body -->
+</div>
+```
+
+Both filters are Shopify-compat. `inline_asset_content` fetches the FR content at render time and wraps it in `<style>` — the CSS bytes are **not** baked into `content`, so a later CSS edit still flows through the normal asset update path.
+
+## Placement
+
+Prepend the tag at the **top** of `index.liquid`. Never append at the end.
+
+- Templates that end with a `{% schema %}` block don't render anything after `{% endschema %}`, so appending would put the tag in dead space.
+- Prepending is uniform whether or not the template has a schema block.
+- Cascade impact is intentional: inline `<style>` blocks or later template-body CSS override the theme-level stylesheet on equal specificity — which is what theme authors typically expect.
+
+## Worked example
+
+Starting state — `product/default/`:
+
+```
+product/default/
+├── index.liquid       ← <h1>Product</h1>… (no stylesheet reference yet)
+├── styles.css         ← 780 bytes of CSS
+└── variables.json
+```
+
+`wc -c` says 780 bytes → below the 2 KB threshold → inline.
+
+**Step 1 — move the file:**
+
+```
+mv product/default/styles.css assets/template-product-default.css
+```
+
+**Step 2 — edit `product/default/index.liquid`, prepend the tag:**
+
+```liquid
+{{ 'template-product-default.css' | inline_asset_content }}
+<h1>Product</h1>
+<!-- rest of body -->
+{% schema %}
+{ "name": "Product" }
+{% endschema %}
+```
+
+**Step 3 — lint:**
+
+```
+fluid theme lint --json
+```
+
+Parse the JSON, fix any issues, re-run until clean.
+
+**Step 4 — dev-server sanity check:**
+
+If `fluid theme dev` is running, refresh the product page in the browser. Confirm the stylesheet is emitted (either as inline `<style>` or `<link>` per your emission choice) and the layout looks the same.
+
+Move on to the next `<themeable_type>/<name>/styles.css`.
+
+## Skip conditions
+
+Skip these templates entirely:
+
+- **`mysite/*/styles.css`** — mysite render path is separate; column stays as-is.
+- **`layouts/*.liquid`**, **`locales/*.json`**, **`config/*.json`** — never had per-template CSS.
+- **Templates whose local `index.liquid` already contains `asset_url | stylesheet_tag` or `inline_asset_content`** — they've already been migrated once. The `<themeable_type>/<name>/styles.css` file that lingers next to them is a leftover, **but do not delete it blindly**: a theme author who missed the memo may have edited it after the migration and now has real work sitting in that file. Read the local `styles.css` and the corresponding `assets/template-*.css` (the filename referenced by the injected Liquid tag). If they're byte-identical, delete the leftover — no data at risk. If they differ, stop, show the user the diff, and ask what to keep — merging into the asset, discarding the leftover, or replacing the asset. Never silently discard bytes.
+
+## What good looks like after the migration
+
+Run `find . -path ./assets -prune -o -name styles.css -print` — the only match should be the theme-root `styles.css` (the theme-level "custom" stylesheet). No per-template `styles.css` files remain.
+
+Run `ls assets/template-*.css` — every template that used to have CSS is now represented as an asset.
+
+Every migrated template's `index.liquid` starts with a `{{ 'template-*.css' | ... }}` expression.
+
+`fluid theme lint --json` is clean.
+
+`fluid theme push` reports no "Skipped … styles.css" warning and no 422.
+
+## Anti-patterns
+
+- **Appending the tag at the end of `index.liquid`.** Dead space after `{% schema %}`. Always prepend.
+- **Refactoring the CSS while migrating.** Two changes at once — hard to review, easy to break. Do the byte-for-byte move first, refactor later in its own commit.
+- **Skipping the lint step.** The validator catches missing assets, dangling Liquid expressions, and other easy misses.
+- **Pushing from within this skill.** Not this skill's job. Hand the reshaped repo back to the user; they decide when to push.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "files": [
     "dist",
@@ -27,7 +27,7 @@
     "open": "^10.0.0",
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
-    "@fluid-app/fluid-cli": "0.1.13"
+    "@fluid-app/fluid-cli": "0.1.12"
   },
   "devDependencies": {
     "@swc/core": "^1.15.18",
@@ -39,9 +39,9 @@
     "tsdown": "^0.21.0",
     "typescript": "^5",
     "@fluid-app/api-client-core": "0.1.0",
+    "@fluid-app/typescript-config": "0.0.0",
     "@fluid-app/theme-schema": "0.1.0",
-    "@fluid-app/themes-api-client": "0.1.0",
-    "@fluid-app/typescript-config": "0.0.0"
+    "@fluid-app/themes-api-client": "0.1.0"
   },
   "engines": {
     "node": ">=18.0.0"