@see-ms/converter 1.0.0 → 1.1.0

package/README.md

@@ -1,308 +1,350 @@
 # @see-ms/converter
 
-CLI tool for converting HTML exports to Nuxt 3 projects with automatic CMS integration.
+SeeMS converts Webflow HTML exports into Nuxt 3 projects with a reviewable CMS manifest, Strapi schemas/seed data, and
+an inline editing overlay.
 
-## Features
+The goal is not just HTML-to-Vue syntax. SeeMS tries to preserve the site, explain what it found, componentize obvious
+reusable sections, make content editable, and wire a developer-friendly Strapi workflow.
 
-✨ **Automatic Conversion**
+## Quick Start
 
-- Convert HTML to Vue components
-- Transform `<a>` tags to `<NuxtLink>` with proper routing
-- Normalize all asset paths automatically
-
-🎨 **Asset Management**
-
-- CSS files → `assets/css/`
-- Images, fonts, JS → `public/assets/`
-- Auto-generate Vite plugin for path resolution (For Webflow)
+```bash
+cms analyze ./webflow-export
+cms convert ./webflow-export ./nuxt-site
+```
 
-🔧 **Smart Transforms**
+Use `--skip-prompts` for repeatable runs:
 
-- Extract and deduplicate embedded styles
-- Remove unnecessary attributes (srcset, sizes)
-- Clean up script tags and inline code
-- Format output with Prettier
+```bash
+cms convert ./webflow-export ./nuxt-site \
+  --config ./see-ms.config.ts \
+  --skip-prompts
+```
 
-📦 **Boilerplate Support**
+## Full Step-By-Step Usage
 
-- Clone from GitHub repository
-- Copy from local directory
-- Works with your custom Nuxt boilerplate
+### 1. Build or install the CLI
 
----
+When working from this monorepo:
 
-## Installation
+```bash
+pnpm install
+pnpm --filter @see-ms/types build
+pnpm --filter @see-ms/editor-overlay build
+pnpm --filter @see-ms/converter build
+```
 
-### Quick Use (npx - no installation)
+Then use:
 
 ```bash
-npx @see-ms/converter convert <webflow-export> <output-dir> [options]
+node packages/converter/dist/cli.mjs --help
 ```
 
-### Global Installation
+If installed globally or through `npx`, use `cms` in place of `node packages/converter/dist/cli.mjs`.
 
-```bash
-npm install -g @see-ms/converter
-# or
-pnpm add -g @see-ms/converter
+### 2. Export your Webflow site
+
+Your Webflow export should contain HTML plus asset folders:
+
+```text
+webflow-export/
+  index.html
+  about.html
+  products/item.html
+  css/
+  images/
+  fonts/
+  js/
 ```
 
-Then use anywhere:
+Nested pages are supported.
+
+### 3. Analyze the export
+
+Run analysis before generating anything:
 
 ```bash
-cms convert <webflow-export> <output-dir> [options]
+cms analyze ./webflow-export
 ```
 
----
+This previews pages, Nuxt routes, assets, shared component candidates, and warnings.
 
-## Usage
+### 4. Convert to Nuxt
 
-### Basic Conversion
+Run the interactive converter:
 
 ```bash
-cms convert ./my-webflow-export ./my-nuxt-site
+cms convert ./webflow-export ./nuxt-site
 ```
 
-### With Boilerplate (Recommended)
+With a Nuxt boilerplate:
 
 ```bash
-# From GitHub
 cms convert ./webflow-export ./nuxt-site \
-  --boilerplate git@github.com:username/nuxt-boilerplate.git
-
-# From local directory
-cms convert ./webflow-export ./nuxt-site \
-  --boilerplate /path/to/local/boilerplate
+  --boilerplate /path/to/nuxt-boilerplate
 ```
 
-### Full Example
-
-```bash
-cms convert ./project-html ./project-nuxt \
-  --boilerplate git@github.com:username/repo-boilerplate.git \
-  --cms strapi
+The converter writes:
+
+```text
+nuxt-site/
+  pages/
+  components/
+  assets/
+  public/cms-manifest.json
+  cms-schemas/
+  cms-seed/seed-data.json
+  strapi-bootstrap/
+  see-ms.config.ts
+  see-ms-report.md
+  see-ms-report.json
 ```
 
----
+### 5. Review the report and config
 
-## Options
+Start with:
 
-| Option                       | Description                                  | Default |
-|------------------------------|----------------------------------------------|---------|
-| `-b, --boilerplate <source>` | GitHub URL or local path to Nuxt boilerplate | none    |
-| `-o, --overrides <path>`     | Path to overrides JSON file                  | none    |
-| `--generate-schemas`         | Generate CMS schemas after conversion        | false   |
-| `--cms <type>`               | CMS type: strapi, contentful, or sanity      | strapi  |
+```text
+nuxt-site/see-ms-report.md
+nuxt-site/see-ms.config.ts
+nuxt-site/public/cms-manifest.json
+```
 
----
+Use the report to check pages, routes, assets, components, editable fields, collections, schemas, seed data, and
+warnings.
 
-## What Gets Converted
+Use `see-ms.config.ts` to make future runs repeatable.
 
-### HTML → Vue Components
+### 6. Repeat conversion without prompts
 
-**Before (Webflow):**
+After reviewing config, rerun non-interactively:
 
-```html
-<!-- index.html -->
-<a href="about.html">About</a>
-<img src="images/logo.svg" srcset="..." sizes="...">
+```bash
+cms convert ./webflow-export ./nuxt-site \
+  --config ./nuxt-site/see-ms.config.ts \
+  --skip-prompts
 ```
 
-**After (Nuxt):**
+### 7. Create or connect Strapi
 
-```vue
-<!-- pages/index.vue -->
-<script setup lang="ts">
-  // Page: index
-</script>
+If you do not have Strapi yet:
 
-<template>
-  <div class="page-index">
-    <NuxtLink to="/about">About</NuxtLink>
-    <img src="/assets/images/logo.svg">
-  </div>
-</template>
+```bash
+cms scaffold-strapi ./strapi-app
 ```
 
-### Asset Structure
+Or scaffold it during conversion:
 
+```bash
+cms convert ./webflow-export ./nuxt-site \
+  --scaffold-strapi ./strapi-app
 ```
-webflow-export/              nuxt-project/
-├── css/                  →  ├── assets/css/
-├── images/               →  ├── public/assets/images/
-├── fonts/                →  ├── public/assets/fonts/
-├── js/                   →  ├── public/assets/js/
-└── *.html                →  └── pages/*.vue
-```
-
-### Auto-Generated Files
-
-- ✅ `utils/webflow-assets.ts` - Vite plugin for CSS path resolution on Webflow files
-- ✅ `assets/css/main.css` - Extracted embedded styles
-- ✅ Updated `nuxt.config.ts` with CSS imports
-
----
 
-## Transformations Applied
+If you already have Strapi:
 
-### Links
-
-- `<a href="about.html">` → `<NuxtLink to="/about">`
-- `<a href="../index.html">` → `<NuxtLink to="/">`
-- `<a href="index.html">` → `<NuxtLink to="/">`
-- External links remain as `<a>` tags
-
-### Images
-
-- `images/logo.svg` → `/assets/images/logo.svg`
-- Removes `srcset` and `sizes` attributes
-- Normalizes relative paths
-
-### Styles
-
-- Extracts `.global-embed` styles (For Webflow)
-- Deduplicates repeated styles
-- Adds to `assets/css/main.css`
-
-### Scripts
-
-- Removes all inline `<script>` tags
-- Cleans up Webflow-specific JavaScript
-
----
+```bash
+cms setup-strapi ./nuxt-site ./strapi-app
+```
 
-## Output Structure
+If the target Strapi directory does not exist yet, `setup-strapi` can create it:
 
-```
-my-nuxt-site/
-├── pages/
-│   ├── index.vue
-│   └── others.cue
-│ 
-├── assets/
-│   └── css/
-│       ├── normalize.css
-│       ├── components.css
-│       ├── webflow.css
-│       └── main.css
-├── public/
-│   └── assets/
-│       ├── images/
-│       ├── fonts/
-│       └── js/
-├── utils/
-│   └── webflow-assets.ts
-└── nuxt.config.ts (updated)
+```bash
+cms setup-strapi ./nuxt-site ./strapi-app --scaffold
 ```
 
----
+### 8. Run Nuxt and Strapi
 
-## After Conversion
-
-1. **Install dependencies:**
+In the Nuxt project:
 
 ```bash
-   cd my-nuxt-site
-   pnpm install
+cd ./nuxt-site
+pnpm install
+pnpm dev
 ```
 
-2. **Start development server:**
+In the Strapi project:
 
 ```bash
-   pnpm dev
+cd ./strapi-app
+npm run develop
 ```
 
-3. **Your site should be running!** 🎉
+Use the package manager you chose when scaffolding Strapi.
 
----
+### 9. Open the inline editor
 
-## Requirements
+Open the Nuxt app normally:
 
-- Node.js >= 18
-- A Webflow export (HTML, CSS, images, fonts)
-- (Optional) A Nuxt 3 boilerplate
+```text
+http://localhost:3000
+```
 
----
+Open preview/editing mode:
 
-## Tips
+```text
+http://localhost:3000?preview=true
+```
 
-### Using Your Own Boilerplate
+The inline editor reads `public/cms-manifest.json` and lets you edit text, rich text, links, images, and icons, then
+save/publish through Strapi.
 
-If you have a standard Nuxt boilerplate for all projects:
+### 10. Use the fixture for local testing
 
-1. Create a GitHub repo with your boilerplate
-2. Use it in every conversion:
+From this repo:
 
 ```bash
-   cms convert ./webflow ./output --boilerplate git@github.com:you/boilerplate.git
+node packages/converter/dist/cli.mjs analyze packages/converter/fixtures/webflow-basic
+
+node packages/converter/dist/cli.mjs convert \
+  packages/converter/fixtures/webflow-basic \
+  /private/tmp/see-ms-fixture-output \
+  --skip-prompts \
+  --no-editor
 ```
 
-### Webflow Export Tips
+## Workflow
+
+1. **Analyze** scans pages, routes, assets, and reusable component candidates.
+2. **Plan** guides you through collections, shared components, seed content, and editor wiring.
+3. **Convert** writes Nuxt pages and preserves nested asset folders.
+4. **CMS** writes `public/cms-manifest.json`, Strapi schemas, and optional seed data.
+5. **Editor** installs the inline editor overlay for `?preview=true`.
+
+Every conversion writes:
+
+- `see-ms.config.ts` for repeatable settings
+- `see-ms-report.md` for a human-readable summary
+- `see-ms-report.json` for automation
+- `public/cms-manifest.json` as the provider-neutral source of truth
+
+## Interactive Conversion
+
+By default, `cms convert` opens a small wizard:
+
+- confirms input, output, boilerplate, and CMS provider
+- previews discovered pages and routes
+- previews shared component candidates
+- asks for collection hints when none exist in config
+- asks whether to generate seed content
+- asks whether to wire the inline editor
+
+The wizard is designed for developers: it explains what the converter sees before it writes the final project.
+
+## Config File
+
+SeeMS writes and reads `see-ms.config.ts`:
+
+```ts
+import type {SeeMSConfig} from "@see-ms/types";
+
+const config: SeeMSConfig = {
+    cms: {provider: "strapi"},
+    collections: [
+        {className: "blog-card", name: "blog_posts"}
+    ],
+    components: {
+        enabled: true,
+        minOccurrences: 2,
+        include: ["nav", "header", "footer"]
+    },
+    ignore: {
+        selectors: [".sr-only"],
+        classes: ["decorative-icon"]
+    },
+    editor: {
+        enabled: true,
+        previewParam: "preview"
+    }
+};
 
-- Export from Webflow: **Site Settings → Export Code**
-- Make sure to include all assets
-- Check that images are properly linked
+export default config;
+```
 
-### Handling Custom Code
+CLI flags can override the config for a single run, but config is the durable source of truth.
 
-If your Webflow site has custom JavaScript that you need:
+## Detection Model
 
-1. The converter removes inline scripts for clean Vue components
-2. Port necessary JavaScript to Vue composables or plugins
-3. Add to your Nuxt `plugins/` or `composables/` folders
+SeeMS detects editable fields from generated Vue templates:
 
----
+- headings, paragraphs, spans, list items, and leaf text nodes
+- rich text when nested formatting is present
+- images and icons as media fields
+- links as `{ url, text, newTab }`
+- collections from `data-cms-collection` or configured classes
+- shared components from repeated nav/header/footer/top-level structures
 
-## Troubleshooting
+Use Webflow custom attributes for stronger hints:
 
-### `nuxt.config.ts not found`
+```html
+<h1 data-cms="hero-heading">Solar finance made simple</h1>
+<div data-cms-collection="faq-items">...</div>
+<p data-cms-ignore>Decorative helper text</p>
+```
+
+## Strapi Setup
 
-The converter expects a `nuxt.config.ts` file. Either:
+For v1, Strapi is the supported CMS provider.
 
-- Use a boilerplate that has one, or
-- The converter will create a minimal one if no boilerplate is specified
+If you do not have a Strapi project yet, scaffold one:
 
-### Assets not loading
+```bash
+cms scaffold-strapi ./strapi-app
+```
 
-Make sure the `webflow-assets.ts` plugin is imported in your `nuxt.config.ts`:
+Or do it as part of conversion:
 
-```typescript
-import webflowAssets from './utils/webflow-assets'
+```bash
+cms convert ./webflow-export ./nuxt-site \
+  --scaffold-strapi ./strapi-app
+```
 
-export default defineNuxtConfig({
-    vite: {
-        plugins: [webflowAssets()]
+For repeatable runs, put it in config:
+
+```ts
+const config: SeeMSConfig = {
+    cms: {
+        provider: "strapi",
+        strapi: {
+            scaffold: true,
+            directory: "./strapi-app",
+            packageManager: "npm",
+            install: true
+        }
     }
-})
+};
 ```
 
-### Routes not working
+Use `--no-strapi-install` if you want SeeMS to create the Strapi files but skip dependency installation.
 
-Check that your `pages/` directory is enabled in Nuxt. It should be automatic, but verify in `nuxt.config.ts`:
+If you already have a Strapi project:
 
-```typescript
-export default defineNuxtConfig({
-    pages: true
-})
+```bash
+cms setup-strapi ./nuxt-site ./strapi-app
+cms generate-schemas ./nuxt-site/public/cms-manifest.json --type strapi
 ```
 
----
-
-## Contributing
+The manifest stays provider-neutral so Contentful and Sanity adapters can be added later without changing the detection
+model.
 
-Issues and pull requests welcome!
+## Inline Editor
 
-## License
+When enabled, SeeMS wires `@see-ms/editor-overlay`.
 
-MIT
+Open the generated Nuxt site with:
 
----
+```text
+http://localhost:3000?preview=true
+```
 
-## Related Packages
+The editor reads `cms-manifest.json`, then supports:
 
-- [@see-ms/types](../types) - Shared TypeScript types
-- [@see-ms/editor-overlay](../editor-overlay) - Inline CMS editor (coming soon)
+- click-to-edit text and headings
+- basic rich text controls
+- link text, URL, and new-tab editing
+- image/icon path replacement
+- draft restore/discard
+- save and publish through generated Nuxt API routes
 
----
+## Fixtures And Local Test Projects
 
-**Made with ❤**
+- `packages/converter/fixtures/webflow-basic` is a small repeatable Webflow-style fixture.