@pie-element/cli 0.1.1

package/src/utils/compatibility.ts

@@ -0,0 +1,182 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+/**
+ * ESM package.json validation result
+ */
+export interface EsmPackageValidation {
+  hasTypeModule: boolean;
+  hasExportsField: boolean;
+  hasMainExport: boolean;
+  hasControllerExport: boolean;
+  sideEffectsFree: boolean;
+  mainExportIsEsm: boolean;
+  controllerExportIsEsm: boolean;
+}
+
+/**
+ * ESM player validation result for an element
+ */
+export interface EsmValidationResult {
+  compatible: boolean;
+  packageJson: EsmPackageValidation;
+  blockers: string[];
+  warnings: string[];
+}
+
+/**
+ * Runtime-ish validation for ESM player readiness (CDN resolution / module parse).
+ * Note: this is NOT a full browser execution test, but it provides production-like signal
+ * by verifying CDN URLs resolve and the returned JS parses as an ES module.
+ */
+export interface EsmRuntimeValidationResult {
+  /**
+   * Whether this element passed the runtime-ish probe.
+   * When false, see `errors` for details.
+   */
+  compatible: boolean;
+  /** The CDN base URL used for probing (e.g. https://esm.sh). */
+  cdnBaseUrl: string;
+  /** Version that was probed (usually the upstream package.json version). */
+  version: string;
+  /** Whether the package entrypoint URL resolved (HTTP 200). */
+  entryOk: boolean;
+  /** Whether the controller URL resolved (HTTP 200). */
+  controllerOk: boolean;
+  /** Whether the returned JS for the entry parsed as an ES module. */
+  entryParseOk: boolean;
+  /** Whether the returned JS for the controller parsed as an ES module. */
+  controllerParseOk: boolean;
+  /** Any errors/warnings collected during probe. */
+  errors: string[];
+
+  /**
+   * Probe details (for deep/transitive validation)
+   */
+  probeMode?: 'shallow' | 'deep';
+  maxDepth?: number;
+  maxModules?: number;
+  fetchedModules?: number;
+  fetchedOk?: number;
+  firstFailingUrl?: string;
+}
+
+/**
+ * Compatibility report structure
+ */
+export interface CompatibilityReport {
+  elements: string[];
+  pieLibPackages: string[];
+  blockedElements: Record<string, string[]>;
+  elementDetails: Record<string, ElementDetail>;
+  pieLibDetails: Record<string, PieLibDetail>;
+
+  // ESM player validation
+  esmPlayerReady: string[];
+  esmValidation: Record<string, EsmValidationResult>;
+  /**
+   * Whether ESM player validation (package.json structure / exports) was run as part of analysis.
+   * Optional for backwards compatibility with older reports.
+   */
+  esmPlayerValidationEnabled?: boolean;
+
+  // Runtime-ish validation (CDN probes)
+  esmRuntimeValidationEnabled?: boolean;
+  esmRuntimeCdnBaseUrl?: string;
+  esmRuntimeValidation?: Record<string, EsmRuntimeValidationResult>;
+
+  // Student UI only (elements where student UI is ESM-ready but authoring isn't)
+  studentUIOnly?: string[];
+
+  lastAnalyzed: string;
+  summary: {
+    totalElements: number;
+    compatibleElements: number;
+    blockedElements: number;
+    studentUIOnlyElements?: number;
+    esmPlayerReady: number;
+    esmRuntimeReady?: number;
+    totalPieLibPackages: number;
+    compatiblePieLibPackages: number;
+  };
+}
+
+export interface ElementDetail {
+  compatible: boolean;
+  directDeps: string[];
+  pieLibDeps: string[];
+  pieElementDeps: string[];
+  blockers: string[];
+
+  // Separate analysis for student UI vs authoring
+  studentUI?: {
+    compatible: boolean;
+    blockers: string[];
+  };
+  configure?: {
+    compatible: boolean;
+    blockers: string[];
+  };
+  controller?: {
+    compatible: boolean;
+    blockers: string[];
+  };
+}
+
+export interface PieLibDetail {
+  compatible: boolean;
+  usedBy: string[];
+  blockers: string[];
+}
+
+export async function loadCompatibilityReport(path: string): Promise<CompatibilityReport> {
+  if (!existsSync(path)) {
+    throw new Error(`Compatibility report not found at: ${path}`);
+  }
+
+  const content = await readFile(path, 'utf-8');
+  return JSON.parse(content) as CompatibilityReport;
+}
+
+export function isElementCompatible(element: string, report: CompatibilityReport): boolean {
+  return report.elements.includes(element);
+}
+
+export function isPieLibPackageCompatible(pkg: string, report: CompatibilityReport): boolean {
+  return report.pieLibPackages.includes(pkg);
+}
+
+export function getElementBlockers(element: string, report: CompatibilityReport): string[] {
+  return report.blockedElements[element] || [];
+}
+
+/**
+ * Check if an element is ESM player ready (no CommonJS deps + proper ESM package structure)
+ */
+export function isElementEsmPlayerReady(element: string, report: CompatibilityReport): boolean {
+  return report.esmPlayerReady.includes(element);
+}
+
+/**
+ * Check if an element has student UI ready (even if configure/controller aren't)
+ */
+export function isElementStudentUIReady(element: string, report: CompatibilityReport): boolean {
+  const detail = report.elementDetails[element];
+  if (!detail) return false;
+
+  // If fully compatible, student UI is ready
+  if (detail.compatible) return true;
+
+  // Check if student UI is explicitly marked as compatible
+  return detail.studentUI?.compatible === true;
+}
+
+/**
+ * Get ESM validation details for an element
+ */
+export function getEsmValidation(
+  element: string,
+  report: CompatibilityReport
+): EsmValidationResult | null {
+  return report.esmValidation[element] || null;
+}

package/src/utils/conversion.ts

@@ -0,0 +1,153 @@
+/**
+ * JavaScript to TypeScript conversion utilities
+ */
+
+export interface ConversionMetadata {
+  sourcePath: string;
+  commit: string;
+}
+
+export interface ConversionResult {
+  code: string;
+  hasDefaultObjectExport: boolean;
+}
+
+/**
+ * Convert JavaScript to TypeScript
+ */
+export function convertJsToTs(jsCode: string, metadata: ConversionMetadata): ConversionResult {
+  // We intentionally do NOT transform the JavaScript syntax.
+  // Goal: keep upstream source as-is, while letting the monorepo's TS/Vite pipeline build it.
+  // TypeScript diagnostics are suppressed for synced files.
+  let tsCode = jsCode;
+  const hasDefaultObjectExport = false;
+
+  // Convert CommonJS module.exports to ES modules
+  tsCode = convertModuleExportsToEsm(tsCode);
+
+  // Must be at the very top of the file to reliably suppress TypeScript diagnostics.
+  // We keep synced files buildable even when upstream JS has type issues.
+  const tsNoCheck = `// @ts-nocheck\n`;
+
+  // Add sync metadata header
+  const header = `/**
+ * @synced-from ${metadata.sourcePath}
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+`;
+  return { code: tsNoCheck + header + tsCode, hasDefaultObjectExport };
+}
+
+/**
+ * Convert CommonJS module.exports to ES module exports
+ */
+function convertModuleExportsToEsm(content: string): string {
+  // Match: module.exports = { key: value, key2: value2, ... };
+  const moduleExportsPattern = /module\.exports\s*=\s*\{([\s\S]*?)\};?/;
+  const match = content.match(moduleExportsPattern);
+
+  if (!match) {
+    return content;
+  }
+
+  const [fullMatch, objectContent] = match;
+
+  // Parse the object content into key-value pairs
+  const exports: string[] = [];
+  const lines = objectContent.split('\n');
+
+  let currentKey: string | null = null;
+  let currentValue: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed === '{' || trimmed === '}') continue;
+
+    // Check if this line starts a new key
+    const keyMatch = trimmed.match(/^(\w+):\s*(.*)/);
+    if (keyMatch) {
+      // Save previous export if any
+      if (currentKey) {
+        const value = currentValue.join('\n').replace(/,\s*$/, ''); // Remove trailing comma
+        exports.push(`export const ${currentKey} =\n${value};`);
+      }
+
+      // Start new export
+      currentKey = keyMatch[1];
+      currentValue = [keyMatch[2]];
+    } else {
+      // Continuation of current value
+      currentValue.push(line);
+    }
+  }
+
+  // Save last export
+  if (currentKey) {
+    const value = currentValue.join('\n').replace(/,\s*$/, '');
+    exports.push(`export const ${currentKey} =\n${value};`);
+  }
+
+  // Replace the module.exports block with ES module exports
+  const esmExports = exports.join('\n\n');
+  return content.replace(fullMatch, esmExports);
+}
+
+/**
+ * Convert JSX to TSX
+ */
+export function convertJsxToTsx(jsxCode: string, metadata: ConversionMetadata): ConversionResult {
+  // We intentionally do NOT transform the JavaScript/JSX syntax.
+  // Goal: keep upstream source as-is, while letting the monorepo's TS/Vite pipeline build it.
+  // TypeScript diagnostics are suppressed for synced files.
+  const tsxCode = jsxCode;
+  const hasDefaultObjectExport = false;
+
+  // Must be at the very top of the file to reliably suppress TypeScript diagnostics.
+  // We keep synced files buildable even when upstream JSX has type issues.
+  const tsNoCheck = `// @ts-nocheck\n`;
+
+  // Add sync metadata header
+  const header = `/**
+ * @synced-from ${metadata.sourcePath}
+ * @auto-generated
+ *
+ * This file is automatically synced from pie-elements and converted to TypeScript.
+ * Manual edits will be overwritten on next sync.
+ * To make changes, edit the upstream JavaScript file and run sync again.
+ */
+
+`;
+  return { code: tsNoCheck + header + tsxCode, hasDefaultObjectExport };
+}
+
+/**
+ * Fix imports from default export files
+ * Some files export default objects but are imported with named imports
+ */
+export function fixImports(content: string, hasDefaultObjectExport: boolean): string {
+  if (!hasDefaultObjectExport) {
+    return content;
+  }
+
+  // Convert: import { something } from './file'
+  // To: import * as file from './file'
+  // This is needed when the imported file has export default {}
+  return content.replace(
+    /import\s+{\s*([^}]+)\s*}\s+from\s+(['"]\.\/[^'"]+['"])/g,
+    (_match, _imports, path) => {
+      // Extract filename from path
+      const filename =
+        path
+          .replace(/['"]/g, '')
+          .split('/')
+          .pop()
+          ?.replace(/\.\w+$/, '') || 'module';
+      return `import * as ${filename} from ${path}`;
+    }
+  );
+}

package/src/utils/git.ts

@@ -0,0 +1,63 @@
+import { execSync } from 'node:child_process';
+
+export function getCurrentCommit(cwd: string): string {
+  try {
+    return execSync('git rev-parse HEAD', { cwd, encoding: 'utf8' }).trim();
+  } catch (error) {
+    throw new Error(`Failed to get current commit: ${error}`);
+  }
+}
+
+export function getCurrentCommitShort(cwd: string): string {
+  try {
+    return execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf8' }).trim();
+  } catch (error) {
+    throw new Error(`Failed to get short commit: ${error}`);
+  }
+}
+
+export function getCommitsSince(since: string, cwd: string): string[] {
+  try {
+    const output = execSync(`git log ${since}..HEAD --oneline`, {
+      cwd,
+      encoding: 'utf8',
+    }).trim();
+
+    if (!output) return [];
+    return output.split('\n');
+  } catch (error) {
+    throw new Error(`Failed to get commits since ${since}: ${error}`);
+  }
+}
+
+export function getFileModifiedDate(filePath: string, cwd: string): Date {
+  try {
+    const timestamp = execSync(`git log -1 --format=%ct -- "${filePath}"`, {
+      cwd,
+      encoding: 'utf8',
+    }).trim();
+
+    return new Date(Number.parseInt(timestamp, 10) * 1000);
+  } catch (error) {
+    throw new Error(`Failed to get file modification date: ${error}`);
+  }
+}
+
+export function getCommitDetails(commit: string, cwd: string): string {
+  try {
+    return execSync(`git show --stat ${commit}`, {
+      cwd,
+      encoding: 'utf8',
+    });
+  } catch (error) {
+    throw new Error(`Failed to get commit details: ${error}`);
+  }
+}
+
+export function getAuthorName(cwd: string): string {
+  try {
+    return execSync('git config user.name', { cwd, encoding: 'utf8' }).trim();
+  } catch (_error) {
+    return 'Unknown';
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,69 @@
+export class Logger {
+  constructor(private verbose: boolean = false) {}
+
+  isVerbose(): boolean {
+    return this.verbose;
+  }
+
+  info(message: string): void {
+    console.log(message);
+  }
+
+  debug(message: string): void {
+    if (this.verbose) {
+      console.log(message);
+    }
+  }
+
+  warn(message: string): void {
+    console.warn(`⚠️  ${message}`);
+  }
+
+  error(message: string): void {
+    console.error(`❌ ${message}`);
+  }
+
+  success(message: string): void {
+    console.log(`✅ ${message}`);
+  }
+
+  section(title: string): void {
+    console.log(`\n${title}`);
+    console.log('='.repeat(title.length));
+  }
+
+  /**
+   * Show a progress message (only in verbose mode)
+   * In non-verbose mode, use progressStart/progressComplete instead
+   */
+  progress(message: string): void {
+    if (this.verbose) {
+      console.log(`  ${message}`);
+    }
+  }
+
+  /**
+   * Show start of an operation (always shown)
+   */
+  progressStart(message: string): void {
+    process.stdout.write(message);
+  }
+
+  /**
+   * Complete a progress operation with success
+   */
+  progressComplete(details?: string): void {
+    if (details) {
+      console.log(` ✓ ${details}`);
+    } else {
+      console.log(' ✓');
+    }
+  }
+
+  /**
+   * Complete a progress operation with a count
+   */
+  progressCompleteWithCount(count: number, label: string): void {
+    console.log(` ✓ (${count} ${label})`);
+  }
+}

package/src/utils/package-json.ts

@@ -0,0 +1,43 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+export interface PackageJson {
+  name: string;
+  version: string;
+  private?: boolean;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export async function loadPackageJson(path: string): Promise<PackageJson> {
+  const content = await readFile(path, 'utf-8');
+  return JSON.parse(content) as PackageJson;
+}
+
+export async function writePackageJson(path: string, pkg: PackageJson): Promise<void> {
+  const content = `${JSON.stringify(pkg, null, 2)}\n`;
+  await writeFile(path, content, 'utf-8');
+}
+
+export function extractDependencies(content: string): string[] {
+  const deps = new Set<string>();
+
+  // Match import statements
+  const importRegex = /import\s+.+\s+from\s+['"]([^'"]+)['"]/g;
+  let match: RegExpExecArray | null = importRegex.exec(content);
+
+  while (match !== null) {
+    const dep = match[1];
+    // Skip relative imports
+    if (!dep.startsWith('.') && !dep.startsWith('/')) {
+      // Extract package name (handle scoped packages)
+      const pkgName = dep.startsWith('@')
+        ? dep.split('/').slice(0, 2).join('/')
+        : dep.split('/')[0];
+      deps.add(pkgName);
+    }
+    match = importRegex.exec(content);
+  }
+
+  return Array.from(deps).sort();
+}

package/tests/sync-package-manager.test.ts

@@ -0,0 +1,112 @@
+import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it } from 'vitest';
+import { SCRIPTS } from '../src/lib/upstream/sync-constants.js';
+import {
+  ensureElementPackageJson,
+  ensurePieLibPackageJson,
+} from '../src/lib/upstream/sync-package-manager.js';
+
+const createConfig = (rootDir: string) =>
+  ({
+    pieElements: join(rootDir, 'upstream', 'pie-elements'),
+    pieLib: join(rootDir, 'upstream', 'pie-lib'),
+    pieElementsNg: rootDir,
+    syncControllers: true,
+    syncReactComponents: true,
+    syncPieLib: true,
+    skipDemos: true,
+    upstreamCommit: 'test',
+  }) as any;
+
+const createElementBase = async (elementDir: string) => {
+  await mkdir(join(elementDir, 'src'), { recursive: true });
+  await writeFile(
+    join(elementDir, 'src', 'index.ts'),
+    'export default class TestElement {}\n',
+    'utf-8'
+  );
+};
+
+const readBuildScript = async (elementDir: string): Promise<string> => {
+  const pkgJson = JSON.parse(await readFile(join(elementDir, 'package.json'), 'utf-8'));
+  return pkgJson.scripts.build;
+};
+
+describe('ensureElementPackageJson iife build script generation', () => {
+  it('uses IIFE build script when vite.config.iife.ts exists', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pie-cli-sync-test-'));
+    const elementDir = join(rootDir, 'packages', 'elements-react', 'test-element');
+
+    await createElementBase(elementDir);
+    await writeFile(join(elementDir, 'vite.config.iife.ts'), 'export default {};\n', 'utf-8');
+
+    const changed = await ensureElementPackageJson(
+      'test-element',
+      elementDir,
+      createConfig(rootDir)
+    );
+    expect(changed).toBe(true);
+
+    const buildScript = await readBuildScript(elementDir);
+    expect(buildScript).toBe(SCRIPTS.BUILD_WITH_IIFE);
+  });
+
+  it('uses standard build script when no IIFE files exist', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pie-cli-sync-test-'));
+    const elementDir = join(rootDir, 'packages', 'elements-react', 'test-element');
+
+    await createElementBase(elementDir);
+
+    const changed = await ensureElementPackageJson(
+      'test-element',
+      elementDir,
+      createConfig(rootDir)
+    );
+    expect(changed).toBe(true);
+
+    const buildScript = await readBuildScript(elementDir);
+    expect(buildScript).toBe(SCRIPTS.BUILD);
+  });
+});
+
+describe('ensurePieLibPackageJson', () => {
+  it('pins math-rendering to shared mathjax adapter workspace package', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pie-cli-sync-test-'));
+    const libDir = join(rootDir, 'packages', 'lib-react', 'math-rendering');
+
+    await mkdir(join(libDir, 'src'), { recursive: true });
+    await writeFile(join(libDir, 'src', 'index.ts'), 'export {};\n', 'utf-8');
+
+    const changed = await ensurePieLibPackageJson('math-rendering', libDir, createConfig(rootDir));
+    expect(changed).toBe(true);
+
+    const pkgJson = JSON.parse(await readFile(join(libDir, 'package.json'), 'utf-8'));
+    expect(pkgJson.dependencies).toEqual({
+      '@pie-element/shared-math-rendering-mathjax': 'workspace:*',
+    });
+  });
+
+  it('adds workspace deps detected from pie-lib source imports', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pie-cli-sync-test-'));
+    const libDir = join(rootDir, 'packages', 'lib-react', 'math-input');
+    const renderUiDir = join(rootDir, 'packages', 'lib-react', 'render-ui');
+
+    await mkdir(join(libDir, 'src'), { recursive: true });
+    await mkdir(renderUiDir, { recursive: true });
+    await writeFile(
+      join(libDir, 'src', 'index.ts'),
+      "import { color } from '@pie-lib/render-ui';\nexport { color };\n",
+      'utf-8'
+    );
+
+    const changed = await ensurePieLibPackageJson('math-input', libDir, createConfig(rootDir));
+    expect(changed).toBe(true);
+
+    const pkgJson = JSON.parse(await readFile(join(libDir, 'package.json'), 'utf-8'));
+    expect(pkgJson.dependencies).toMatchObject({
+      '@pie-lib/render-ui': 'workspace:*',
+    });
+  });
+});