@augeo/smelt 1.2.2 → 1.3.0

package/docs/library-conversion-plan.md

@@ -1,419 +0,0 @@
----
-status: draft
----
-
-# Converting Smelt to a Library + CLI
-
-Plan for turning this repo from "a Shopify theme that happens to have a custom
-build script" into "an npm package that other Shopify themes install and use."
-Companion to [`build-spec.md`](./build-spec.md) — the build spec describes the
-compiler's behavior; this doc describes the path from where we are to publishing
-it as a tool.
-
-## Vision
-
-Today, Smelt _is_ a theme. After this work:
-
-- Smelt is published as **`@augeo/smelt`** (`npm i -D @augeo/smelt`), matching
-  the scope used by
-  [`@augeo/assay`](https://www.npmjs.com/package/@augeo/assay).
-- It exposes a **CLI** (`npx smelt build`, `npx smelt dev`).
-- It ships a **baseline component layer** that consumers can use as-is.
-- Consumer themes have their own `src/` that **layers on top** of Smelt's
-  baseline — files in the consumer layer shadow matching baseline files.
-- This repo keeps a working `example/` consumer theme that exercises the package
-  end-to-end (mirrors how [`assay`](https://github.com/seanhealy/assay) is
-  organized).
-
-The build engine's _behavior_ doesn't change much. The walker, render rewriter,
-esbuild bundle, CSS/JS inlining, banner, and indent handling all transfer almost
-as-is. The new pieces are **layer resolution**, **CLI packaging**, and the
-**inside-out reorganization** of this repo.
-
-## Design Decisions
-
-All five confirmed during planning. Listed here so the rationale lives next to
-the decision and is easy to revisit if a future constraint forces a rethink.
-
-### 1. Shadowing is per-file, not per-component
-
-If a consumer provides only `button.css`, they get Smelt's `button.liquid` +
-`button.ts` with their CSS swapped in. Each of `<name>.{liquid,ts,css,test.ts}`
-resolves independently across layers.
-
-- **Why:** maximally flexible; lets consumers tweak just styling without forking
-  the logic.
-- **Cost:** harder to reason about than "you own the whole component." Need
-  clear error messages when a shadow drifts (e.g. consumer's CSS references a
-  class Smelt's liquid no longer renders).
-
-### 2. `@/` and `./` resolve against the **merged** layer tree
-
-When Smelt's `tabs.liquid` does `{% render '@/components/icon' %}`, it resolves
-through the layered tree — so a consumer's icon shadow is picked up. Same for
-esbuild's resolution of `@/utilities/...` imports.
-
-- **Why:** without this, layering is just "drop in alternates" rather than true
-  overrides — the baseline can't be visibly customized through its
-  collaborators.
-- **Cost:** consumers can break Smelt internals by shadowing a utility
-  carelessly. Mitigation: discipline + clear documentation about which surface
-  is considered stable (same model as Gatsby component shadowing or Material UI
-  theme overrides).
-
-### 3. We ship **source**, not built artifacts
-
-The published package contains raw `.liquid` / `.ts` / `.css` for the baseline
-layer. The consumer's `smelt build` is what compiles them.
-
-- **Why:** required for layering to work at the source level. If we shipped
-  pre-built `built--*.liquid`, consumers couldn't shadow a baseline component's
-  CSS in isolation.
-- **Cost:** consumer build time scales with Smelt's component count. Acceptable
-  for now; revisit if pain.
-
-### 4. One published package, not split
-
-`@augeo/smelt` ships the CLI **and** the baseline components together. No
-`@augeo/smelt-cli` + `@augeo/smelt-baseline` split yet.
-
-- **Why:** split is cheap to do later if a reason emerges (e.g. alternate
-  baselines, plugin authors who want just the CLI). No reason today.
-- **Cost:** baseline component changes force a new version of the CLI package
-  too. Acceptable until baseline surface grows.
-
-### 5. Optional `smelt.config.ts`, minimal surface
-
-A config file exists but is optional. For v1 it has exactly one field: `layers`.
-Everything else stays convention until proven necessary.
-
-```ts
-// smelt.config.ts
-import { defineConfig } from "@augeo/smelt";
-
-export default defineConfig({
-	layers: ["./src", "@augeo/smelt"],
-});
-```
-
-If the file doesn't exist, the resolver defaults to `["./src", "@augeo/smelt"]`
-— first wins. Output dirs, build options, etc. stay hardcoded for now.
-
-- **Why:** consumers will eventually want custom layer ordering (multiple
-  baselines, brand overrides, plugin layers). The config makes this expressible
-  without arg-parsing gymnastics. Limiting v1 to `layers` alone keeps the door
-  open without committing to a sprawling surface.
-- **Cost:** another file format to maintain — small. `defineConfig` is a pure
-  type-identity helper (same pattern as Vite, Vitest, etc.).
-- **Future:** add `output`, `extensions`, build options when a real consumer
-  needs them.
-
-## CLI Surface
-
-| Command       | What it does                                                       |
-| ------------- | ------------------------------------------------------------------ |
-| `smelt build` | One-shot build of all layers → consumer's flat output directories  |
-| `smelt dev`   | Watch mode: rebuild affected components on source file change      |
-| `smelt init`  | (Future) Scaffold a new consumer theme repo with sensible defaults |
-
-**`smelt dev` is build-watch only** — it rebuilds affected components on source
-change and exits on Ctrl-C. Consumer composes it with the Shopify CLI in their
-own `package.json`:
-
-```jsonc
-{
-	"scripts": {
-		"dev": "concurrently 'smelt dev' 'shopify theme dev'",
-	},
-}
-```
-
-Rationale: keeps Smelt from having a runtime dependency on Shopify CLI being
-installed, and matches how Vite / Next / etc handle their `dev` command (they
-don't try to run framework-adjacent servers for you).
-
-## Architecture Changes
-
-Most of the engine survives intact. What changes:
-
-| Area             | Before                                     | After conversion                                                                            |
-| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| Entry point      | `src/scripts/build.ts` runs immediately    | `lib/cli.ts` defines commands via [citty](https://github.com/unjs/citty), calls library API |
-| Roots            | Hardcoded `ROOT = resolve(".")`, `SRC = …` | `resolveContext()` figures out consumer cwd + layer paths                                   |
-| Component walker | Walks one tree                             | Walks N layer trees, per-file merge by priority                                             |
-| Render rewriter  | Looks up in single component map           | Looks up in merged component map                                                            |
-| esbuild          | `tsconfig` points at this repo's tsconfig  | Uses consumer's tsconfig if present; alias plugin resolves `@/` per layer                   |
-| Output dirs      | Hardcoded `sections/`, etc.                | Resolved relative to consumer cwd                                                           |
-| Watch mode       | Doesn't exist                              | New: incremental rebuild on file change in any layer                                        |
-| Dev mode         | `npm run dev` = shopify CLI only           | `smelt dev` = build watcher; consumer composes with `shopify theme dev`                     |
-| Banner           | `GENERATED FROM src/...`                   | `GENERATED FROM <layer-tagged source path>`                                                 |
-
-## Phased Execution Plan
-
-Each phase is a coherent chunk that can be verified, reviewed, and merged
-independently. We don't need to do them all in one shot — they're sized so the
-repo stays useful between phases.
-
-### Phase 1 — Inside-out reorganization (minimal engine touchups)
-
-Move all theme content into `example/` and reframe the root as a future library,
-without touching the engine architecturally. The build script gets ~4 lines of
-hardcoded path updates so it keeps working against the new layout — proper
-context-driven refactor happens in Phase 2. After this phase, `example/` is the
-test bed for everything that follows (mirroring how assay uses its own
-`example/`).
-
-Deliverables:
-
-- Create directories: `example/`, `lib/` (placeholder for Phase 2),
-  `components/` (placeholder for Phase 3), `dist/` (gitignored)
-- Move theme content into `example/`:
-  - Output dirs: `sections/`, `snippets/`, `blocks/`
-  - Theme files: `layout/`, `templates/`, `config/`, `locales/`, `assets/`
-  - Theme config: `.theme-check.yml`, `.shopifyignore`
-  - Test config: `vitest.config.ts`
-- Move demo component: `src/components/button/` →
-  `example/src/components/button/`
-- Patch `src/scripts/build.ts`: change `SRC` to point at `example/src`, prefix
-  output dir constants with `example/`. ~4 line change; engine is still
-  hardcoded but works against the new layout.
-- Update root `package.json`:
-  - Strip theme scripts (`dev`, `push`, `pull`, `theme:check`, `theme:fix`)
-  - Keep `build` (still at root for now; outputs into `example/`)
-- Create `example/package.json`:
-  - Theme scripts (cwd=`example/`): `dev`, `push`, `pull`, `theme:check`,
-    `theme:fix`
-  - `build`: `tsx ../src/scripts/build.ts` (interim — Phase 2 makes this clean)
-  - `test`: vitest against `example/`'s built output
-- Update `.gitattributes` linguist-generated patterns to use the `example/`
-  prefix
-- Update CI workflow: lint/typecheck at root, then `cd example` for build,
-  tests, theme-check, and the `git status` diff guard
-- Update docs:
-  - `AGENTS.md` — restructure to reflect the library-root + consumer-example
-    layout. Note that `example/` is the integration test bed.
-  - `docs/build-spec.md` — reframe the worked example as "in the consumer's
-    repo." Pipeline behavior description unchanged.
-  - `README.md` — minor update to reflect theme commands now live in `example/`.
-
-Verification: `npm run build` at root produces files in `example/`; from
-`example/`: `npm test && npm run theme:check` succeeds and the built output
-matches today's root-as-theme output (after the move).
-
-### Phase 2 — Engine refactor + citty CLI + `file:..` link
-
-Pull the build script out of `src/scripts/` and into `lib/` as a properly
-context-driven library, exposed through a citty CLI compiled to a real bin via
-tsdown. After this phase, the engine no longer assumes anything about "where the
-consumer's theme lives" — it accepts a `BuildContext`, **and `example/` consumes
-it like a real npm consumer** via `"@augeo/smelt": "file:.."`. This catches bin
-/ shebang / entry-point bugs early without waiting for full packaging in
-Phase 4.
-
-**Types policy:** no dedicated `types.ts` file. Define types alongside the code
-that primarily uses them — if a second module needs the same type, it imports
-from the defining module. Keeps things easy to mutate; revisit only if genuine
-ambiguity emerges.
-
-**Bundler policy:** tsdown owns _library packaging_ (the CLI bin, and later the
-programmatic exports + d.ts). esbuild stays for _per-component runtime bundling_
-inside the build engine. Two bundlers, two distinct concerns; not a swap.
-
-Deliverables:
-
-- `lib/build.ts` — exports `async function build(context: BuildContext)`.
-  `BuildContext` lives in this file.
-- `lib/cli.ts` — defines commands via [citty](https://github.com/unjs/citty),
-  dispatches to `build` (only command for now). Picked over cac/Cliffy/oclif for
-  deep TS inference, lightweight footprint, and active maintenance in the UnJS
-  ecosystem.
-- `tsdown.config.ts` — bundles `lib/cli.ts` → `dist/cli.mjs` with a
-  `#!/usr/bin/env node` shebang. (Grows in Phase 4 to add `dist/index.js` +
-  d.ts + exports map.)
-- Delete `src/scripts/` entirely (no shim — its one caller, `example/`'s `build`
-  script, gets repointed via the bin)
-- Root `package.json` (mirrors assay's script conventions):
-  - Add `bin.smelt` → `./dist/cli.mjs`
-  - `build` script: `tsdown` (this package's artifact = `dist/cli.mjs`)
-  - `build:watch` script: `tsdown --watch` (iteration ergonomic)
-  - `verify` script: `lint:fix && typecheck` — fast root quality gate
-  - `test` script: `npm run build && npm test --prefix example` — integration
-    chain
-  - `prepare` script: `npm run build` (keeps `npm install` ergonomic; needed
-    because the example's bin resolution depends on `dist/cli.mjs` existing)
-  - `prepublishOnly` script: `npm run build` (publish-time safety)
-  - Add `citty` to `dependencies`; add `tsdown` to `devDependencies`
-- `example/package.json` (intentionally consumer-shaped):
-  - `devDependencies`: `"@augeo/smelt": "file:.."`
-  - `build` script: `smelt build` (resolves through the linked bin)
-  - `test` script: `typecheck → build → vitest → theme:check` — example's full
-    check, called by root's `npm test`
-  - Run `npm install` in `example/` once to set up the symlink
-- Update `tsconfig.json` `include` from `src/**/*.ts` → `lib/**/*.ts`
-- Update doc references (`AGENTS.md`, `docs/build-spec.md`) to the new
-  `lib/build.ts` path
-- `npm run verify` at root and `npm run verify` in `example/` both pass; diff
-  check confirms no output drift
-
-Verification: from `example/`, `npx smelt build` (via `npm run build`) produces
-byte-identical output to Phase 1 (modulo any intentional banner reformat).
-Resolution flows `example/node_modules/@augeo/smelt` → symlink → repo root, so
-edits to `lib/cli.ts` rebuild `dist/cli.mjs` on next example build and are
-picked up automatically.
-
-### Phase 3 — Layer resolution
-
-Introduce the `Layer` concept and per-file merging. Build engine accepts an
-ordered list of layer paths; walker merges; render rewriter and esbuild resolver
-consult the merged tree. With `example/` in place since Phase 1, this is
-exercised against a real consumer setup rather than synthetic scaffolding.
-
-Deliverables:
-
-- `lib/resolver.ts` — walks N layers, returns merged component list. Each
-  `ResolvedComponent` has `liquid`/`ts`/`css`/`test` slots that independently
-  track which layer they came from. New types (`Layer`, `ComponentSource`,
-  `ResolvedComponent`, `ComponentType`) live here; `lib/build/build.ts` imports
-  them.
-- `BuildContext` drops `cwd` and gains `layers: Layer[]`. Output dirs are always
-  relative (`sections/`, `snippets/`, `blocks/`), resolved against the first
-  layer (the consumer root).
-- `lib/build/build.ts` walker rewritten to consume the merged list from the
-  resolver (no more local `walkSrc`).
-- `lib/build/command.ts` uses `import.meta.url` + `fileURLToPath` to locate the
-  published package's root (the second layer); the consumer's layer is
-  `process.cwd()`. Default layers: `[<consumer>, "@augeo/smelt"]`.
-- Promote the button into the root `src/components/button/` baseline so there's
-  something to shadow. Drop a `button.css` shadow into
-  `example/src/components/button/` to demonstrate partial override.
-- esbuild plugin for `@/...` resolution against the merged layer tree —
-  **deferred until a real component uses `@/...` TS imports**. The demo button
-  doesn't, so this is YAGNI for now.
-- Root `vitest.config.ts` (matches assay's pattern) picks up
-  `lib/**/*.test.ts` + `src/**/*.test.ts`. Root `test` script chains
-  `vitest run` between the lib build and example's tests.
-- `lib/resolver.test.ts` — colocated unit tests covering baseline-only, partial
-  CSS shadow, full consumer shadow, first-wins ordering, disjoint layers, and
-  dead-code (consumer slot with no liquid anchor) scenarios via `mkdtemp`
-  fixtures.
-- `src/components/button/button.test.ts` — assay-style functional test (renders,
-  accepts `label` arg, applies CSS class). **Deferred** until the baseline has a
-  built target vitest can render against; the integration test in `example/`
-  already verifies the button compiles end-to-end.
-
-Verification: in `example/`, the built button uses the consumer's CSS
-(`background: #f3c724`, pill-shaped) while the `liquid` and `ts` slots come from
-baseline (`@augeo/smelt/src/components/button/...`, visible in the banner).
-
-### Phase 4 — Packaging
-
-Make the library a real publishable npm package. The CLI bin already comes out
-of tsdown (set up in Phase 2); this phase grows the same tsdown config to also
-emit a programmatic entry point and adds the `package.json` metadata an npm
-consumer needs.
-
-Deliverables:
-
-- Grow `tsdown.config.ts` to add a second entry: `lib/build.ts` →
-  `dist/index.js` with `.d.ts`
-- `package.json` updates:
-  - `exports` map for `dist/index.js` (programmatic use) and the bin
-  - `files: ["dist", "components"]`
-  - `peerDependencies`: nothing yet (we bundle esbuild)
-  - `dependencies`: esbuild, citty (already moved out of devDeps in Phase 2 for
-    citty; confirm esbuild placement)
-- `prepublishOnly` script that runs `npm run lib:build` to ensure `dist/` is
-  fresh
-- `npm pack` round-trip: install the tarball into `example/` (instead of
-  `file:..`) and confirm it still builds. Catches missing-`files`-entry and
-  shebang-permission bugs that `file:..` masks.
-
-Verification: `npm pack` produces a tarball;
-`cd example && npm install ../smelt-0.0.0.tgz && npx smelt build` works
-end-to-end against the packed artifact (not just `file:..`). After verification,
-restore the `file:..` link so day-to-day dev keeps working live.
-
-### Phase 5 — CI and verify chain
-
-CI now verifies two things: the library compiles cleanly, and the example
-consumer builds correctly with no drift.
-
-Deliverables:
-
-- Workflow `.github/workflows/verify.yml`:
-  - lint, typecheck, library unit tests, library build (`tsdown`)
-  - then `cd example`, `npm install`, `npx smelt build`, vitest
-  - finally `git diff --exit-code` to catch stale built files in
-    `example/sections`, `example/snippets`, `example/blocks`
-- Root `npm run verify` mirrors CI: lint:fix → typecheck → test → build → cd
-  example && verify
-- `.claude/settings.json` adjusted for the new script set
-
-Verification: open a draft PR with a deliberately stale built file in
-`example/`; CI should fail on the diff check.
-
-### Phase 6 — First publish + first real consumer
-
-Go from "works locally" to "is the tool we use."
-
-Deliverables:
-
-- Publish `@augeo/smelt` 0.1.0
-- Pick one of the Augeo themes (or coverlet, if we're feeling ambitious) to
-  migrate as the first real consumer
-- Document the migration path in `docs/`
-
-Verification: real-world consumer's CI is green using the published package.
-
-## Documentation Updates
-
-Done as part of the relevant phase, listed here for visibility:
-
-- `AGENTS.md` (Phase 1) — restructure to reflect the library-root +
-  consumer-example layout. Will get a second pass in Phase 4 to add a section
-  pointing consumers at the README / `docs/consumer-guide.md`.
-- `README.md` (Phase 4) — rewrite as "what Smelt is, how to install, how to
-  use." Move the current command table to `example/README.md`.
-- `docs/build-spec.md` (Phase 1) — reframe the worked example as "in the
-  consumer's repo, where Smelt was installed." The pipeline behavior description
-  is unchanged.
-- `docs/consumer-guide.md` (Phase 4, new) — install, write components, shadow
-  baseline, run dev/build/test. The new user-facing doc.
-- `docs/library-architecture.md` (Phase 3, new, optional) — internal notes on
-  layer resolution and the engine API. Lives next to `build-spec.md`.
-
-## Open Questions / Risks
-
-- **Shadowing footguns.** A consumer shadowing a utility used by multiple
-  baseline components creates a non-local change. Error messages need to make
-  this obvious. May need a `smelt explain` command long-term (shows resolution
-  for a given component).
-- **Tests-against-built-output composes with layers how?** Today vitest runs
-  against `./sections`, `./snippets`, `./blocks` — those contain built output
-  from BOTH baseline + consumer post-merge. So tests work the same way. But:
-  should consumers be able to write tests for baseline components without
-  copy-pasting them? Probably yes; defer until use case appears.
-- **What happens when a consumer references a baseline component via
-  `@/components/button` but doesn't shadow it?** Resolver finds it in the
-  baseline layer, build emits `snippets/built--components--button.liquid` into
-  the consumer's output dirs. ✓ same naming as if consumer had written it.
-  Banner notes the file came from `smelt/components/button/`.
-
-## Out of Scope (For This Conversion)
-
-Things we explicitly defer beyond the scope of this conversion:
-
-- **Plugin system.** No third-party extension points yet. Layers cover the
-  customization story for v1.
-- **Multiple baseline packages.** v1 has exactly one baseline (the library's own
-  `components/`). Consumers can't mix `smelt-baseline-a` + `smelt-baseline-b`.
-  Adding that is a layered version of layering and can wait.
-- **`props.ts` runtime validation.** Already deferred in `build-spec.md`. Still
-  deferred here.
-- **Workspace conversion.** Single package is the right call until a reason
-  emerges to split. Triggers documented in [conversation history / future ADR].
-- **Component documentation site.** Out of scope; baseline components are
-  documented via their own colocated comments + a future `docs/components.md`
-  catalog.
-- **Migration tooling for existing themes.** v1 consumer migration is manual.
-  Tooling (e.g. `smelt migrate-from-dawn`) is way out of scope.