feat: create-estreuv scaffolding CLI (pure + pair modes)

packages/create-estreuv — npm create estreuv my-app:
- bin/estreuv.js: commander CLI (init/dev/update/add/remove,
  default->init, estreui-style arg routing)
- init: mode select (pure | pair), --pure/--pair/--no-install flags
  - pure: self-contained templates/pure (import map + tiles, no build)
  - pair: delegates EstreUI shell to create-estreui, then applies
    EstreUV overlay (estreuv-tiles.js + import map injection +
    deps + ESTREUV-PAIR.md handler snippet)
- dev: reused from create-estreui verbatim (zero drift, PM 008 R5)
- update/add/remove: pure=npm + import-map guidance, pair=delegate
- templates/pure + templates/pair-overlay
- test/smoke.mjs: module load + pure scaffold E2E (--no-install)
- CI: create-estreuv smoke step

Design: max-share with create-estreui (depend, not fork); common
scaffold core is a later follow-up (PM 008 R5). Pure mode E2E
verified (all smoke checks pass). create-estreuv stays 0.1.0 for
first publish (no changeset — changesets only bumps).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: SoliEstre

.github/workflows/ci.yml

@@ -22,3 +22,5 @@ jobs:
         run: npm run measure
       - name: Type declarations (D4 — .d.ts emit must stay green)
         run: npm run types --workspace=packages/estreuv
+      - name: create-estreuv smoke test
+        run: npm run test --workspace=packages/create-estreuv

package-lock.json

@@ -0,0 +1,39 @@
+# create-estreuv
+
+Scaffolding tool for [EstreUV.js](https://github.com/SoliEstre/EstreUV.js) projects.
+
+```sh
+npm create estreuv my-app
+# or
+npm create estreuv my-app -- --pure      # pure EstreUV app
+npm create estreuv my-app -- --pair      # EstreUI + EstreUV pair app
+```
+
+## Project types
+
+| Type | What you get |
+| --- | --- |
+| **pure** | Minimal EstreUV app — import map (lit + estreuv), tile demo, `estreuv dev` server. No build, no EstreUI. |
+| **pair** | An EstreUI app (scaffolded via `create-estreui`) + the EstreUV overlay (import map, `scripts/estreuv-tiles.js`, deps) and `ESTREUV-PAIR.md` with the one page-handler wiring step. |
+
+## CLI (`estreuv`)
+
+The package also installs an `estreuv` bin in scaffolded projects:
+
+| Command | Behavior |
+| --- | --- |
+| `estreuv dev` | HTTPS dev server (shared with `create-estreui` — mkcert/openssl auto-cert). |
+| `estreuv update` | `npm update estreuv lit @lit/context`; a pair app also refreshes the EstreUI shell. |
+| `estreuv add <pkg>` | Pure: `npm install` + import-map guidance. Pair: delegates to `create-estreui` (vendored). |
+| `estreuv remove <pkg>` | Symmetric to `add`. |
+
+## Design
+
+`dev` is reused from `create-estreui` verbatim (zero EstreUI-specific logic →
+no fork drift). Pair mode delegates the EstreUI shell to `create-estreui`
+rather than duplicating its vendored-asset logic (PM 008 R5: maximize
+sharing; a common scaffold core is a later follow-up).
+
+## License
+
+MIT © SoliEstre

packages/create-estreuv/README.md

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const program = new Command();
+const packageJson = require('../package.json');
+
+const initCommand = require('../lib/commands/init');
+const devCommand = require('../lib/commands/dev');
+const updateCommand = require('../lib/commands/update');
+const addCommand = require('../lib/commands/add');
+const removeCommand = require('../lib/commands/remove');
+
+program
+  .name('estreuv')
+  .description('CLI for EstreUV.js — micro-Rimwork (Lit class primitive), sister to EstreUI.js')
+  .version(packageJson.version);
+
+program.addCommand(initCommand);
+program.addCommand(devCommand);
+program.addCommand(updateCommand);
+program.addCommand(addCommand);
+program.addCommand(removeCommand);
+
+// If no args, default to init
+const args = process.argv.slice(2);
+if (!args.length) {
+    program.parse([...process.argv, 'init']);
+} else {
+    const knownCommands = ['init', 'update', 'dev', 'add', 'remove', 'help'];
+    const firstArg = args[0];
+
+    // If first arg is not a known command and not a flag, treat it as a project name for init
+    if (!knownCommands.includes(firstArg) && !firstArg.startsWith('-')) {
+        program.parse([...process.argv.slice(0, 2), 'init', ...args]);
+    } else {
+        program.parse(process.argv);
+    }
+}

packages/create-estreuv/bin/estreuv.js

@@ -0,0 +1,39 @@
+const { Command } = require('commander');
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const program = new Command('add');
+
+function isPairProject(cwd) {
+    return fs.existsSync(path.join(cwd, 'scripts/estreUi-main.js'))
+        || fs.existsSync(path.join(cwd, 'scripts/estreUi-core.js'));
+}
+
+program
+    .description('Add a frontend package (npm install; pair app vendors it via create-estreui)')
+    .argument('<package>', 'Package name')
+    .action(async (packageName) => {
+        const cwd = process.cwd();
+        try {
+            if (isPairProject(cwd)) {
+                // Pair app uses the EstreUI vendored model — delegate.
+                const bin = require.resolve('create-estreui/bin/estreui.js');
+                execSync(`node "${bin}" add ${packageName}`, { cwd, stdio: 'inherit' });
+                return;
+            }
+            // Pure EstreUV app: npm install + import-map guidance (ESM path
+            // varies per package, so we don't guess the map entry).
+            console.log(`Installing ${packageName}...`);
+            execSync(`npm install ${packageName}`, { cwd, stdio: 'inherit' });
+            console.log(`✓ Installed ${packageName}`);
+            console.log(`\nNext: add an import-map entry in index.html, e.g.`);
+            console.log(`    "${packageName}": "/node_modules/${packageName}/<esm-entry>.js"`);
+            console.log(`then import it from scripts/tiles.js.`);
+        } catch (err) {
+            console.error('Error adding package:', err.message);
+            process.exit(1);
+        }
+    });
+
+module.exports = program;

packages/create-estreuv/lib/commands/add.js

@@ -0,0 +1,24 @@
+// `estreuv dev` — reuse create-estreui's dev server verbatim.
+//
+// The dev command in create-estreui is a generic HTTPS static server
+// (mkcert/openssl auto-cert, SPA-friendly, Service-Worker-Allowed header).
+// It has zero EstreUI-specific logic, so create-estreuv shares it directly
+// rather than forking — minimizes drift (PM 008 R5). Works for both the
+// pure EstreUV importmap app and the EstreUI + EstreUV pair app.
+
+let devCommand;
+try {
+    devCommand = require('create-estreui/lib/commands/dev');
+} catch (e) {
+    const { Command } = require('commander');
+    devCommand = new Command('dev')
+        .description('Start local HTTPS development server')
+        .action(() => {
+            console.error('❌ `create-estreui` is required for `estreuv dev` but could not be loaded.');
+            console.error('   Install it:  npm i -D create-estreui');
+            console.error('   (' + e.message + ')');
+            process.exit(1);
+        });
+}
+
+module.exports = devCommand;

packages/create-estreuv/lib/commands/dev.js

@@ -0,0 +1,90 @@
+const { Command } = require('commander');
+const inquirer = require('inquirer');
+const path = require('path');
+const fs = require('fs');
+const { copyDir, writeProjectPackageJson, applyEstreuvOverlay, runCreateEstreui } = require('../utils');
+
+const program = new Command('init');
+
+program
+    .description('Initialize a new EstreUV.js project')
+    .argument('[project-name]', 'Project name')
+    .option('--pure', 'Pure EstreUV app (no EstreUI)')
+    .option('--pair', 'EstreUI + EstreUV pair app')
+    .option('--no-install', 'Skip npm install')
+    .action(async (projectName, options) => {
+        // 1. Project name
+        let { name } = { name: projectName };
+        if (!name) {
+            ({ name } = await inquirer.prompt([{
+                type: 'input', name: 'name',
+                message: 'Project name:', default: 'my-estreuv-app'
+            }]));
+        }
+
+        // 2. Mode
+        let mode = options.pure ? 'pure' : options.pair ? 'pair' : null;
+        if (!mode) {
+            ({ mode } = await inquirer.prompt([{
+                type: 'list', name: 'mode', message: 'Project type:',
+                choices: [
+                    { name: 'Pure EstreUV app (Lit micro-Rimwork, no build)', value: 'pure' },
+                    { name: 'EstreUI + EstreUV pair app (EstreUI shell + EstreUV tiles)', value: 'pair' }
+                ],
+                default: 'pure'
+            }]));
+        }
+
+        const projectPath = path.resolve(process.cwd(), name === '.' ? '' : name);
+        const pkgName = name === '.' ? path.basename(process.cwd()) : name;
+
+        try {
+            if (mode === 'pure') {
+                await scaffoldPure(projectPath, pkgName, options.install);
+            } else {
+                await scaffoldPair(projectPath, pkgName, name, options.install);
+            }
+            console.log('\n✓ Project initialized.');
+            console.log(`\n  cd ${name}\n  npm run dev\n`);
+        } catch (error) {
+            console.error('Error initializing project:', error);
+            process.exit(1);
+        }
+    });
+
+async function scaffoldPure(projectPath, pkgName, install) {
+    console.log(`Initializing pure EstreUV app in ${projectPath}...`);
+    fs.mkdirSync(projectPath, { recursive: true });
+
+    const templateDir = path.resolve(__dirname, '../../templates/pure');
+    await copyDir(templateDir, projectPath);
+    console.log('✓ Copied template');
+
+    writeProjectPackageJson(projectPath, pkgName, { pair: false });
+    console.log('✓ Created package.json');
+
+    if (install) require('../utils').installDependencies(projectPath);
+}
+
+async function scaffoldPair(projectPath, pkgName, rawName, install) {
+    console.log(`Initializing EstreUI + EstreUV pair app in ${projectPath}...`);
+
+    // Delegate the EstreUI shell to create-estreui (max share — PM 008 R5).
+    runCreateEstreui(rawName);
+
+    if (!fs.existsSync(projectPath)) {
+        throw new Error('create-estreui did not produce the project directory. Aborting overlay.');
+    }
+
+    // Apply the EstreUV overlay on top of the EstreUI scaffold.
+    const overlayDir = path.resolve(__dirname, '../../templates/pair-overlay');
+    applyEstreuvOverlay(projectPath, overlayDir);
+
+    writeProjectPackageJson(projectPath, pkgName, { pair: true });
+    console.log('✓ Added estreuv / lit / @lit/context to package.json');
+
+    if (install) require('../utils').installDependencies(projectPath);
+    console.log('✓ See ESTREUV-PAIR.md for the one manual page-handler step.');
+}
+
+module.exports = program;

packages/create-estreuv/lib/commands/init.js

@@ -0,0 +1,34 @@
+const { Command } = require('commander');
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const program = new Command('remove');
+
+function isPairProject(cwd) {
+    return fs.existsSync(path.join(cwd, 'scripts/estreUi-main.js'))
+        || fs.existsSync(path.join(cwd, 'scripts/estreUi-core.js'));
+}
+
+program
+    .description('Remove a frontend package (npm uninstall; pair app delegates to create-estreui)')
+    .argument('<package>', 'Package name')
+    .action(async (packageName) => {
+        const cwd = process.cwd();
+        try {
+            if (isPairProject(cwd)) {
+                const bin = require.resolve('create-estreui/bin/estreui.js');
+                execSync(`node "${bin}" remove ${packageName}`, { cwd, stdio: 'inherit' });
+                return;
+            }
+            console.log(`Uninstalling ${packageName}...`);
+            execSync(`npm uninstall ${packageName}`, { cwd, stdio: 'inherit' });
+            console.log(`✓ Removed ${packageName}`);
+            console.log(`\nRemember to remove its import-map entry from index.html and any imports.`);
+        } catch (err) {
+            console.error('Error removing package:', err.message);
+            process.exit(1);
+        }
+    });
+
+module.exports = program;

packages/create-estreuv/lib/commands/remove.js

@@ -0,0 +1,34 @@
+const { Command } = require('commander');
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const program = new Command('update');
+
+function isPairProject(cwd) {
+    // create-estreui scaffolds vendored estreui core assets.
+    return fs.existsSync(path.join(cwd, 'scripts/estreUi-main.js'))
+        || fs.existsSync(path.join(cwd, 'scripts/estreUi-core.js'));
+}
+
+program
+    .description('Update EstreUV (and, for a pair app, the EstreUI shell) to latest')
+    .action(async () => {
+        const cwd = process.cwd();
+        try {
+            console.log('🔄 Updating estreuv / lit / @lit/context...');
+            execSync('npm update estreuv lit @lit/context', { cwd, stdio: 'inherit' });
+
+            if (isPairProject(cwd)) {
+                console.log('🔄 Pair app detected — refreshing EstreUI shell via create-estreui...');
+                const bin = require.resolve('create-estreui/bin/estreui.js');
+                execSync(`node "${bin}" update`, { cwd, stdio: 'inherit' });
+            }
+            console.log('🎉 Update complete.');
+        } catch (err) {
+            console.error('❌ Update failed:', err.message);
+            process.exit(1);
+        }
+    });
+
+module.exports = program;