@pie-element/cli 0.1.1

package/src/commands/packages/init-synced-elements.ts

@@ -0,0 +1,259 @@
+import { Command, Flags } from '@oclif/core';
+import { Logger } from '../../utils/logger.js';
+import { existsSync } from 'node:fs';
+import { readdir, readFile, writeFile, stat as fsStat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const ELEMENTS_REACT_DIR = 'packages/elements-react';
+const PIE_ELEMENTS_DIR = '../pie-elements/packages';
+
+interface PackageTemplate {
+  name: string;
+  private: boolean;
+  version: string;
+  description: string;
+  type: string;
+  main: string;
+  types: string;
+  exports: Record<string, unknown>;
+  files: string[];
+  scripts: Record<string, string>;
+  dependencies: Record<string, string>;
+  peerDependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+  keywords: string[];
+  license: string;
+  repository: {
+    type: string;
+    url: string;
+    directory: string;
+  };
+}
+
+export default class InitSyncedElements extends Command {
+  static override description =
+    'Initialize package.json and vite.config.ts files for synced React elements';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --element=categorize',
+    '<%= config.bin %> <%= command.id %> --dry-run',
+  ];
+
+  static override flags = {
+    element: Flags.string({
+      description: 'Initialize only specified element',
+    }),
+    'dry-run': Flags.boolean({
+      description: 'Show what would be created without making changes',
+      default: false,
+    }),
+    verbose: Flags.boolean({
+      char: 'v',
+      description: 'Show detailed output',
+      default: false,
+    }),
+  };
+
+  private logger = new Logger();
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(InitSyncedElements);
+
+    this.logger = new Logger(flags.verbose);
+
+    this.logger.section('🔧 Initializing synced React elements');
+
+    if (flags['dry-run']) {
+      this.logger.info('   Mode: DRY RUN\n');
+    }
+
+    const elements = await readdir(ELEMENTS_REACT_DIR);
+    let created = 0;
+    let skipped = 0;
+
+    for (const element of elements) {
+      // Skip if filtering by element and this isn't it
+      if (flags.element && element !== flags.element) {
+        continue;
+      }
+
+      const elementDir = join(ELEMENTS_REACT_DIR, element);
+
+      // Skip if not a directory
+      const statResult = await fsStat(elementDir).catch(() => null);
+      if (!statResult?.isDirectory()) {
+        continue;
+      }
+
+      // Skip if src directory doesn't exist
+      if (!existsSync(join(elementDir, 'src'))) {
+        continue;
+      }
+
+      const packageJsonPath = join(elementDir, 'package.json');
+
+      // Skip if package.json already exists
+      if (existsSync(packageJsonPath)) {
+        if (flags.verbose) {
+          this.logger.info(`  ⏭️  ${element}: package.json already exists`);
+        }
+        skipped++;
+        continue;
+      }
+
+      // Read upstream package.json
+      const upstreamPkg = await this.readUpstreamPackageJson(element);
+      if (!upstreamPkg) {
+        this.logger.warn(`  ⚠️  ${element}: Could not read upstream package.json`);
+        continue;
+      }
+
+      // Generate package.json
+      const pkg = this.generatePackageJson(element, upstreamPkg);
+
+      if (!flags['dry-run']) {
+        await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+        this.logger.success(`  ✨ ${element}: Created package.json`);
+      } else {
+        this.logger.info(`  🔍 ${element}: Would create package.json`);
+      }
+
+      // Generate vite.config.ts
+      const viteConfigPath = join(elementDir, 'vite.config.ts');
+      if (!existsSync(viteConfigPath)) {
+        if (!flags['dry-run']) {
+          await writeFile(viteConfigPath, this.generateViteConfig(), 'utf-8');
+          this.logger.success(`  ✨ ${element}: Created vite.config.ts`);
+        } else {
+          this.logger.info(`  🔍 ${element}: Would create vite.config.ts`);
+        }
+      }
+
+      created++;
+    }
+
+    this.logger.section(
+      `\n📊 Summary: ${created} ${flags['dry-run'] ? 'would be created' : 'created'}, ${skipped} skipped`
+    );
+  }
+
+  private async readUpstreamPackageJson(
+    elementName: string
+  ): Promise<Record<string, unknown> | null> {
+    const upstreamPath = join(PIE_ELEMENTS_DIR, elementName, 'package.json');
+
+    if (!existsSync(upstreamPath)) {
+      return null;
+    }
+
+    try {
+      const content = await readFile(upstreamPath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  private generatePackageJson(
+    elementName: string,
+    upstreamPkg: Record<string, unknown>
+  ): PackageTemplate {
+    const deps: Record<string, string> = {};
+
+    // Map upstream dependencies to workspace:* for @pie-lib packages
+    const upstreamDeps = upstreamPkg.dependencies as Record<string, string> | undefined;
+    if (upstreamDeps) {
+      for (const [name] of Object.entries(upstreamDeps)) {
+        if (name.startsWith('@pie-lib/')) {
+          deps[name] = 'workspace:*';
+        } else if (!name.startsWith('react') && name !== 'react-dom') {
+          deps[name] = '*';
+        }
+      }
+    }
+
+    return {
+      name: `@pie-element/${elementName}`,
+      private: true,
+      version: '0.1.0',
+      description: `React implementation of ${elementName} element synced from pie-elements`,
+      type: 'module',
+      main: './dist/index.js',
+      types: './dist/index.d.ts',
+      exports: {
+        '.': {
+          types: './dist/index.d.ts',
+          default: './dist/index.js',
+        },
+      },
+      files: ['dist', 'src'],
+      scripts: {
+        dev: 'vite',
+        build: 'vite build && tsc --emitDeclarationOnly',
+        test: 'vitest run',
+        lint: 'biome check .',
+        'lint:fix': 'biome check --write .',
+      },
+      dependencies: deps,
+      peerDependencies: {
+        react: '^18.0.0',
+        'react-dom': '^18.0.0',
+      },
+      devDependencies: {
+        '@types/react': '^18.2.0',
+        '@types/react-dom': '^18.2.0',
+        '@vitejs/plugin-react': '^4.2.0',
+        typescript: '^5.9.3',
+        vite: '^6.0.0',
+        vitest: '^2.1.0',
+      },
+      keywords: ['pie', 'pie-element', 'react', 'assessment', elementName],
+      license: 'ISC',
+      repository: {
+        type: 'git',
+        url: 'https://github.com/pie-framework/pie-elements-ng.git',
+        directory: `packages/elements-react/${elementName}`,
+      },
+    };
+  }
+
+  private generateViteConfig(): string {
+    return `import { resolve } from 'node:path';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: {
+        index: resolve(__dirname, 'src/index.ts'),
+      },
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: (id) => {
+        return (
+          /^react($|\\/)/.test(id) ||
+          /^react-dom($|\\/)/.test(id) ||
+          /^@pie-lib\\//.test(id) ||
+          /^@pie-element\\//.test(id) ||
+          /^@pie-framework\\//.test(id) ||
+          /^@mui\\//.test(id) ||
+          /^d3-/.test(id) ||
+          id === 'lodash' ||
+          /^lodash\\//.test(id) ||
+          ['prop-types', 'classnames', 'debug'].includes(id)
+        );
+      },
+      output: {
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+      },
+    },
+  },
+});
+`;
+  }
+}

package/src/commands/upstream/README.md

@@ -0,0 +1,444 @@
+# Upstream Commands
+
+This directory contains commands for managing the synchronization between the upstream PIE repositories and this project.
+
+**Audience:** These commands are for maintainers who sync from upstream. Regular developers don't need these commands - synced packages are already committed to git, so just `git pull` to get updates.
+
+## Overview
+
+The PIE Elements NG project syncs code from two upstream repositories:
+
+- **pie-elements** - Contains element controllers and React components
+- **pie-lib** - Contains shared library packages
+
+These commands help manage that synchronization process, analyze ESM compatibility, and track what's been synced.
+
+Synced packages (`packages/elements-react/*` and `packages/lib-react/*`) are committed to git, so regular developers can work without checking out the upstream repositories.
+
+At a high level, the update workflow does more than copy files. It:
+
+- Filters upstream packages via ESM compatibility analysis
+- Syncs controllers, React UI, and pie-lib sources into local packages
+- Converts source files to TypeScript (`.js`→`.ts`, `.jsx`→`.tsx`)
+- Rewrites package metadata (exports, entrypoints, sideEffects)
+- Generates element-specific Vite config and demo metadata
+- Cleans workspace deps and installs updated dependencies
+
+## Commands
+
+### `update` (Recommended)
+
+**The main command you should use!** Combines ESM analysis and syncing in one step.
+
+**Usage:**
+
+```bash
+# Update everything (analyze + sync)
+bun cli upstream:update
+
+# Dry run to see what would change
+bun cli upstream:update --dry-run
+
+# Update specific element
+bun cli upstream:update --element=multiple-choice
+
+# Verbose output
+bun cli upstream:update --verbose
+```
+
+**What it does:**
+
+1. **Analyzes** ESM compatibility of all upstream packages
+2. **Syncs** all compatible packages automatically
+3. **Builds** touched packages (unless --skip-build)
+
+This is the recommended workflow as it ensures the analysis is always fresh before syncing.
+
+---
+
+### `analyze-esm`
+
+Analyzes ESM compatibility of upstream packages to determine what can be safely synced.
+
+**When to use:** When you only want to check compatibility without syncing, or for debugging.
+
+**Usage:**
+
+```bash
+# Analyze all packages
+bun cli upstream:analyze-esm
+
+# Verbose output with dependency details
+bun cli upstream:analyze-esm --verbose
+
+# Include dev dependencies in analysis
+bun cli upstream:analyze-esm --include-dev-deps
+
+# Validate with runtime checks
+bun cli upstream:analyze-esm --validate
+```
+
+**What it does:**
+
+1. Scans all upstream packages for ESM blockers (CommonJS-only dependencies)
+2. Checks element-to-element dependencies for transitive compatibility
+3. Tracks @pie-lib dependencies used by elements
+4. Generates compatibility report at `.compatibility/report.json`
+5. Optional: Runtime validation by actually loading packages
+
+**Output:**
+
+- Lists ESM-compatible elements
+- Lists blocked elements with reasons
+- Shows @pie-lib package compatibility
+- Provides recommendations for fixing issues
+
+**Why run this first?**
+The sync command uses this report to automatically filter out incompatible packages, ensuring you only sync elements that will work as ESM modules.
+
+### `sync`
+
+Synchronizes ESM-compatible code from upstream repositories to this project.
+
+**When to use:** When you've already run `analyze-esm` and want to sync without re-analyzing, or for advanced workflows.
+
+**Usage:**
+
+```bash
+# Sync everything (automatically filters to ESM-compatible packages)
+bun cli upstream:sync
+
+# Dry run to see what would change
+bun cli upstream:sync --dry-run
+
+# Sync specific element
+bun cli upstream:sync --element=multiple-choice
+
+# Verbose output
+bun cli upstream:sync --verbose
+```
+
+**What it does:**
+
+1. **Reads compatibility report** from `analyze-esm` to filter packages
+2. **Controllers**: Syncs from `pie-elements/packages/{element}/controller/src/` to `packages/elements-react/{element}/src/controller/`
+3. **React Components**: Syncs from `pie-elements/packages/{element}/src/` to `packages/elements-react/{element}/src/`
+4. **Pie-Lib**: Syncs from `pie-lib/packages/{package}/src/` to `packages/lib-react/{package}/src/`
+5. **Conversions**: Automatically converts `.js` → `.ts` and `.jsx` → `.tsx`
+6. **Package.json**: Generates ESM-compatible package.json with proper exports
+7. **Build**: Automatically builds touched packages after sync
+
+**Strategy Pattern:**
+The sync command uses the strategy pattern for clean separation:
+
+- `ControllersStrategy` - Handles controller syncing
+- `ReactComponentsStrategy` - Handles React component syncing
+- `PieLibStrategy` - Handles pie-lib package syncing
+
+Each strategy is self-contained and independently testable.
+
+### `track`
+
+Tracks synced packages and their upstream status.
+
+**Usage:**
+
+```bash
+# Show sync status for all packages
+bun cli upstream:track
+
+# Check specific element
+bun cli upstream:track --element=multiple-choice
+```
+
+**What it does:**
+
+1. Shows which packages have been synced
+2. Displays upstream commit hash for each package
+3. Identifies packages that may need updates
+
+## Workflow
+
+### Initial Setup (Maintainers Only)
+
+**Note:** Only needed if you're a maintainer syncing from upstream. Regular developers can skip this.
+
+1. Clone the upstream repositories as siblings to this repo:
+
+   ```bash
+   cd /path/to/projects
+   git clone https://github.com/PieLabs/pie-elements.git
+   git clone https://github.com/PieLabs/pie-lib.git
+   git clone https://github.com/pie-framework/pie-elements-ng.git
+   cd pie-elements-ng
+   ```
+
+2. Run initial analysis to see what's available:
+
+   ```bash
+   bun cli upstream:analyze-esm --verbose
+   ```
+
+### Regular Update Workflow (Simple)
+
+The simplest workflow using the combined `update` command:
+
+1. **Pull upstream changes:**
+
+   ```bash
+   cd ../pie-elements && git pull
+   cd ../pie-lib && git pull
+   cd ../pie-element
+   ```
+
+2. **Check what would change** (dry run):
+
+   ```bash
+   bun cli upstream:update --dry-run --verbose
+   ```
+
+3. **Update everything:**
+
+   ```bash
+   bun cli upstream:update
+   ```
+
+4. **Review, test, and commit:**
+
+   ```bash
+   git diff
+   bun test
+   git add .
+   git commit -m "sync: update from upstream"
+   git push
+   ```
+
+### Incremental Update Workflow (Safer)
+
+For testing changes to individual elements first:
+
+1. **Pull upstream changes:**
+
+   ```bash
+   cd ../pie-elements && git pull
+   cd ../pie-lib && git pull
+   cd ../pie-element
+   ```
+
+2. **Update specific element** (with dry run first):
+
+   ```bash
+   bun cli upstream:update --element=multiple-choice --dry-run
+   bun cli upstream:update --element=multiple-choice
+   ```
+
+3. **Test the element:**
+
+   ```bash
+   bun test packages/elements-react/multiple-choice
+   ```
+
+4. **If good, update all:**
+
+   ```bash
+   bun cli upstream:update
+   ```
+
+5. **Commit and push:**
+
+   ```bash
+   git add .
+   git commit -m "sync: update from upstream"
+   git push
+   ```
+
+### Working with Blocked Elements
+
+If an element is blocked from ESM compatibility:
+
+1. **Check why it's blocked:**
+
+   ```bash
+   bun cli upstream:analyze-esm --verbose | grep element-name
+   ```
+
+2. **Common blockers:**
+   - `lodash` → Replace with native JS or `lodash-es`
+   - `react-dnd` → Upgrade to v16+ (ESM compatible)
+   - Sibling dependencies → Fix the dependency first
+
+3. **Fix in upstream** (preferred):
+   - Create PR in pie-elements to fix the blocker
+   - Wait for merge
+   - Re-analyze and sync
+
+4. **Fix locally** (if urgent):
+   - Sync the element
+   - Manually fix the blocker in the local copy
+   - Document the change
+   - Create upstream PR later
+
+## Advanced Features
+
+### Always-Include Pie-Lib Packages
+
+Some @pie-lib packages (like `controller-utils`) are imported directly in controller code but not declared in element package.json files. To ensure these are always synced, they're defined in the `ALWAYS_INCLUDE_PIE_LIB` constant in [analyze-esm.ts](./analyze-esm.ts):
+
+```typescript
+// PIE lib packages that should always be included if compatible
+// These are packages that may be imported directly in code (e.g., controllers)
+// but not declared in package.json dependencies
+const ALWAYS_INCLUDE_PIE_LIB = [
+  "controller-utils", // Used in controller code via direct imports
+];
+```
+
+**When to add a package here:**
+
+- Package is imported in controller/component code
+- Package is NOT in element package.json dependencies
+- Package should be available for all elements that need it
+
+### Element-Specific Build Configuration
+
+Some elements require special vite configuration (e.g., bundling specific dependencies instead of externalizing them). This is handled automatically by [sync-react-strategy.ts](./sync-react-strategy.ts).
+
+#### Konva Bundling Example
+
+Elements using konva/react-konva (like hotspot, drawing-response) bundle these libraries instead of externalizing them to avoid runtime resolution issues with transitive dependencies:
+
+```typescript
+// In sync-react-strategy.ts
+const konvaElements = ["hotspot", "drawing-response"];
+const shouldBundleKonva = konvaElements.includes(elementName);
+```
+
+This generates a special vite.config.ts that:
+
+- Bundles konva, react-konva, scheduler, and react-reconciler (not externalized)
+- Uses `preserveModules: true` to maintain proper import statements for other externals
+- Avoids CDN import map issues with complex dependency chains while preserving lodash imports
+
+**When to add an element to konvaElements:**
+
+- Element imports konva or react-konva
+- Seeing "schedulerExports is not defined" or similar runtime errors
+- Dependencies have complex transitive chains not suitable for CDN loading
+
+**Why bundle instead of externalize?**
+
+- Element-specific libraries (only 2-3 elements use konva)
+- Complex transitive dependencies (scheduler, react-reconciler)
+- CDN (esm.sh) import paths don't match local import maps
+- Better reliability and performance for specialized packages
+
+### Demo Mode Configuration
+
+Elements with a `docs/demo` directory automatically get demo mode support in their vite.config.ts:
+
+```typescript
+export default defineConfig(({ mode, command }) => ({
+  plugins: [react()],
+  // Only change root for demo mode when serving (not building)
+  root:
+    mode === "demo" && command === "serve"
+      ? resolve(__dirname, "docs/demo")
+      : __dirname,
+  // ... rest of config
+}));
+```
+
+This allows running `bun run demo` in the element package to serve the demo application.
+
+## File Organization
+
+```
+tools/cli/src/commands/upstream/
+├── README.md                        # This file
+├── update.ts                        # Combined update command (recommended)
+├── analyze-esm.ts                   # ESM compatibility analyzer
+├── sync.ts                          # Sync command (orchestration)
+├── track.ts                         # Package tracking command
+├── sync-strategy.ts                 # Strategy interface
+├── sync-controllers-strategy.ts     # Controller sync strategy
+├── sync-react-strategy.ts           # React component sync strategy
+├── sync-pielib-strategy.ts          # Pie-lib sync strategy
+├── sync-filesystem.ts               # File system utilities
+├── sync-package-json.ts             # Package.json utilities
+├── sync-vite-config.ts              # Vite config generation
+├── sync-demo.ts                     # Demo generation utilities
+└── sync-imports.ts                  # Import fixing utilities
+```
+
+## Best Practices
+
+### Do's ✅
+
+- **Always dry-run first** to see what will change
+- **Sync one element at a time** when testing
+- **Review diffs carefully** before committing
+- **Test after syncing** to ensure functionality
+- **Keep upstream siblings up to date** (git pull regularly)
+- **Use ESM-compatible dependencies** to unblock packages
+- **Document breaking changes** in commit messages
+
+### Don'ts ❌
+
+- **Don't modify synced files directly** - changes will be overwritten on next sync
+- **Don't skip the build** - it catches issues early
+- **Don't force-sync incompatible elements** - they won't work as ESM
+- **Don't commit without testing** - broken elements affect everyone
+- **Don't sync without upstream being clean** - use stable commits
+
+## Troubleshooting
+
+### Sync fails with "file not found"
+
+Check that upstream repositories are at the expected locations:
+
+```bash
+ls -la ../pie-elements ../pie-lib
+```
+
+### Build fails after sync
+
+1. Check if dependencies changed in upstream package.json
+2. Run `bun install` to update dependencies
+3. Check for TypeScript errors in synced files
+
+### Element marked as incompatible
+
+Run detailed analysis:
+
+```bash
+bun cli upstream:analyze-esm --verbose --element=element-name
+```
+
+Fix the blockers (see "Working with Blocked Elements" above).
+
+### Import errors after sync
+
+The sync automatically fixes default exports, but some edge cases may require manual fixes:
+
+```typescript
+// If you see errors like "X is not exported from Y"
+// Check if the import needs to be a named import
+import { something } from "./file"; // Instead of default import
+```
+
+## Contributing
+
+When adding new functionality to the sync process:
+
+1. **Utilities** → Add to appropriate utility file (sync-\*.ts)
+2. **New sync type** → Create a new strategy file
+3. **Strategy changes** → Modify the specific strategy file
+4. **Orchestration** → Update sync.ts (main command)
+
+Keep the strategy pattern clean - each strategy should be self-contained.
+
+## Related Documentation
+
+- [REFACTORING.md](../../REFACTORING.md) - Details on the refactoring work
+- [Main CLI README](../../../README.md) - General CLI usage
+- [UPSTREAM_SYNC_GUIDE.md](../../../../../docs/migration/UPSTREAM_SYNC_GUIDE.md) - Detailed sync guide