@pie-element/cli 0.1.1

package/src/commands/upstream/track.ts

@@ -0,0 +1,145 @@
+import { Command, Args } from '@oclif/core';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import {
+  getCurrentCommit,
+  getCommitsSince,
+  getCommitDetails,
+  getAuthorName,
+} from '../../utils/git.js';
+import { Logger } from '../../utils/logger.js';
+import { DEFAULT_PATHS, HISTORY_FILE } from '../../lib/upstream/sync-constants.js';
+
+interface UpstreamState {
+  lastCheck: string;
+  upstreamCommits: {
+    pieElements: string;
+    pieLib: string;
+  };
+  checkedBy: string;
+}
+
+export default class Track extends Command {
+  static override description = 'Track upstream repository changes';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %> show',
+    '<%= config.bin %> <%= command.id %> record',
+    '<%= config.bin %> <%= command.id %> compare <commit-sha>',
+  ];
+
+  static override args = {
+    action: Args.string({
+      description: 'Action to perform',
+      required: true,
+      options: ['show', 'record', 'compare'],
+    }),
+    commit: Args.string({
+      description: 'Commit SHA for compare action',
+      required: false,
+    }),
+  };
+
+  private logger = new Logger();
+
+  public async run(): Promise<void> {
+    const { args } = await this.parse(Track);
+
+    switch (args.action) {
+      case 'show':
+        await this.showCommits();
+        break;
+      case 'record':
+        await this.recordState();
+        break;
+      case 'compare':
+        if (!args.commit) {
+          this.error('Commit SHA required for compare action');
+        }
+        await this.compareCommit(args.commit);
+        break;
+      default:
+        this.error(`Unknown action: ${args.action}`);
+    }
+  }
+
+  private async showCommits(): Promise<void> {
+    this.logger.section('📊 Upstream Repository Status');
+
+    const pieElements = DEFAULT_PATHS.PIE_ELEMENTS;
+    const pieLib = DEFAULT_PATHS.PIE_LIB;
+
+    if (!existsSync(HISTORY_FILE)) {
+      this.logger.warn('No history file found. Run "record" first to establish baseline.');
+      return;
+    }
+
+    const history: UpstreamState = JSON.parse(await readFile(HISTORY_FILE, 'utf-8'));
+
+    this.logger.info(`\nLast checked: ${history.lastCheck}`);
+    this.logger.info(`Checked by: ${history.checkedBy}\n`);
+
+    // Show new commits for pie-elements
+    this.logger.section('📦 pie-elements');
+    const elementsCommits = getCommitsSince(history.upstreamCommits.pieElements, pieElements);
+    if (elementsCommits.length === 0) {
+      this.logger.info('   No new commits');
+    } else {
+      this.logger.info(`   ${elementsCommits.length} new commits:`);
+      for (const commit of elementsCommits.slice(0, 10)) {
+        this.logger.info(`   ${commit}`);
+      }
+      if (elementsCommits.length > 10) {
+        this.logger.info(`   ... and ${elementsCommits.length - 10} more`);
+      }
+    }
+
+    // Show new commits for pie-lib
+    this.logger.section('\n📚 pie-lib');
+    const libCommits = getCommitsSince(history.upstreamCommits.pieLib, pieLib);
+    if (libCommits.length === 0) {
+      this.logger.info('   No new commits');
+    } else {
+      this.logger.info(`   ${libCommits.length} new commits:`);
+      for (const commit of libCommits.slice(0, 10)) {
+        this.logger.info(`   ${commit}`);
+      }
+      if (libCommits.length > 10) {
+        this.logger.info(`   ... and ${libCommits.length - 10} more`);
+      }
+    }
+  }
+
+  private async recordState(): Promise<void> {
+    const pieElements = DEFAULT_PATHS.PIE_ELEMENTS;
+    const pieLib = DEFAULT_PATHS.PIE_LIB;
+
+    const state: UpstreamState = {
+      lastCheck: new Date().toISOString(),
+      upstreamCommits: {
+        pieElements: getCurrentCommit(pieElements),
+        pieLib: getCurrentCommit(pieLib),
+      },
+      checkedBy: getAuthorName(pieElements),
+    };
+
+    await writeFile(HISTORY_FILE, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+
+    this.logger.success('✅ Upstream state recorded');
+    this.logger.info(`   pie-elements: ${state.upstreamCommits.pieElements.substring(0, 8)}`);
+    this.logger.info(`   pie-lib: ${state.upstreamCommits.pieLib.substring(0, 8)}`);
+  }
+
+  private async compareCommit(commit: string): Promise<void> {
+    const pieElements = DEFAULT_PATHS.PIE_ELEMENTS;
+
+    this.logger.section(`📋 Commit Details: ${commit.substring(0, 8)}`);
+
+    try {
+      const details = getCommitDetails(commit, pieElements);
+      this.log(details);
+    } catch (error) {
+      this.error(`Failed to get commit details: ${error}`);
+    }
+  }
+}

package/src/commands/upstream/update.ts

@@ -0,0 +1,110 @@
+import { Command, Flags } from '@oclif/core';
+import { resolve } from 'node:path';
+import AnalyzeEsm from './analyze-esm.js';
+import Sync from './sync.js';
+import { assertReposExist } from '../../lib/upstream/repo-utils.js';
+
+export default class Update extends Command {
+  static override description =
+    'Update from upstream: analyze ESM compatibility and sync compatible packages';
+
+  static override examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --dry-run',
+    '<%= config.bin %> <%= command.id %> --element=multiple-choice',
+    '<%= config.bin %> <%= command.id %> --verbose',
+  ];
+
+  static override flags = {
+    'dry-run': Flags.boolean({
+      description: 'Show what would be synced without making changes',
+      default: false,
+    }),
+    verbose: Flags.boolean({
+      char: 'v',
+      description: 'Show detailed output',
+      default: false,
+    }),
+    element: Flags.string({
+      description: 'Update only specified element',
+    }),
+    'skip-build': Flags.boolean({
+      description: 'Skip building after sync',
+      default: false,
+    }),
+    'include-dev-deps': Flags.boolean({
+      description: 'Include dev dependencies in ESM analysis',
+      default: false,
+    }),
+    validate: Flags.boolean({
+      description: 'Run runtime validation during ESM analysis',
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Update);
+
+    // Verify pie-elements and pie-lib repos exist
+    const pieElementsPath = resolve(process.cwd(), '../pie-elements');
+    const pieLibPath = resolve(process.cwd(), '../pie-lib');
+
+    try {
+      assertReposExist([
+        {
+          label: 'pie-elements repository',
+          path: pieElementsPath,
+          extraMessage: 'Expected upstream repository as a sibling directory.',
+        },
+        {
+          label: 'pie-lib repository',
+          path: pieLibPath,
+          extraMessage: 'Expected upstream repository as a sibling directory.',
+        },
+      ]);
+    } catch (error) {
+      this.error(error instanceof Error ? error.message : String(error));
+    }
+
+    if (flags.verbose) {
+      this.log('');
+      this.log('╔═══════════════════════════════════════════════════════╗');
+      this.log('║         Updating from Upstream Repositories          ║');
+      this.log('╚═══════════════════════════════════════════════════════╝');
+      this.log('');
+      this.log('📊 Step 1/2: Analyzing ESM compatibility...');
+      this.log('');
+    }
+
+    const analyzeFlags = [
+      '--output=.compatibility/report.json',
+      flags.verbose ? '--verbose' : '',
+      flags['include-dev-deps'] ? '--include-dev-deps' : '',
+      flags.validate ? '--validate' : '',
+    ].filter(Boolean);
+
+    await AnalyzeEsm.run(analyzeFlags);
+
+    if (flags.verbose) {
+      this.log('');
+      this.log('─'.repeat(60));
+      this.log('');
+      this.log('🔄 Step 2/2: Syncing compatible packages...');
+      this.log('');
+    }
+
+    const syncFlags = [
+      flags['dry-run'] ? '--dry-run' : '',
+      flags.verbose ? '--verbose' : '',
+      flags.element ? `--element=${flags.element}` : '',
+      flags['skip-build'] ? '--skip-build' : '',
+    ].filter(Boolean);
+
+    await Sync.run(syncFlags);
+
+    if (!flags.verbose) {
+      this.log('');
+      this.log('✅ Update complete!');
+    }
+  }
+}

package/src/commands/verify/controllers.ts

@@ -0,0 +1,166 @@
+import { Command, Flags } from '@oclif/core';
+import { Logger } from '../../utils/logger.js';
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EXCLUDED_UPSTREAM_ELEMENTS } from '../../lib/upstream/sync-constants.js';
+
+type CheckResult = {
+  element: string;
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+};
+
+const ELEMENTS_REACT_DIR = 'packages/elements-react';
+
+function hasAnyControllerSource(elementDir: string): boolean {
+  const base = join(elementDir, 'src', 'controller', 'index');
+  return (
+    existsSync(base + '.ts') ||
+    existsSync(base + '.tsx') ||
+    existsSync(base + '.js') ||
+    existsSync(base + '.jsx')
+  );
+}
+
+export default class VerifyControllers extends Command {
+  static override description =
+    'Verify that element packages will publish controller modules correctly (exports + dist artifacts)';
+
+  static override examples = [
+    'bun run cli <%= command.id %>',
+    'bun cli <%= command.id %>',
+    '<%= config.bin %> <%= command.id %>',
+  ];
+
+  static override flags = {
+    verbose: Flags.boolean({
+      char: 'v',
+      description: 'Show detailed output',
+      default: false,
+    }),
+    element: Flags.string({
+      description: 'Check only specified element',
+    }),
+  };
+
+  private logger = new Logger();
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(VerifyControllers);
+    this.logger = new Logger(flags.verbose);
+
+    this.logger.section('🧩 Verifying published controller modules');
+
+    const items = await readdir(ELEMENTS_REACT_DIR, { withFileTypes: true });
+    const excludedElements = new Set<string>(EXCLUDED_UPSTREAM_ELEMENTS as readonly string[]);
+    let elements = items
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .filter((name) => !excludedElements.has(name));
+
+    if (flags.element) {
+      if (!elements.includes(flags.element)) {
+        this.error(`Element '${flags.element}' not found in ${ELEMENTS_REACT_DIR}`);
+      }
+      elements = [flags.element];
+    }
+
+    const results: CheckResult[] = [];
+    for (const element of elements.sort()) {
+      const elementDir = join(ELEMENTS_REACT_DIR, element);
+      const pkgPath = join(elementDir, 'package.json');
+      if (!existsSync(pkgPath)) {
+        results.push({
+          element,
+          ok: false,
+          errors: ['Missing package.json'],
+          warnings: [],
+        });
+        continue;
+      }
+
+      const hasController = hasAnyControllerSource(elementDir);
+      if (!hasController) {
+        // Nothing to publish for controllers; skip.
+        results.push({ element, ok: true, errors: [], warnings: [] });
+        continue;
+      }
+
+      const pkgRaw = await readFile(pkgPath, 'utf-8');
+      const pkg = JSON.parse(pkgRaw) as any;
+      const exportsObj = pkg?.exports as any;
+      const controllerExport = exportsObj?.['./controller'];
+
+      const errors: string[] = [];
+      const warnings: string[] = [];
+      if (!controllerExport) {
+        errors.push('Missing exports["./controller"] in package.json');
+      } else {
+        const jsPath = controllerExport?.default as string | undefined;
+        const dtsPath = controllerExport?.types as string | undefined;
+
+        if (!jsPath || typeof jsPath !== 'string') {
+          errors.push('exports["./controller"].default is missing');
+        } else {
+          const abs = join(elementDir, jsPath.replace(/^\.\//, ''));
+          if (!existsSync(abs)) {
+            errors.push(`Controller JS artifact missing: ${jsPath}`);
+          }
+        }
+
+        // Types are nice-to-have for TS consumers, but not required for runtime/controller loading.
+        // We'll warn (not fail) if types are missing.
+        if (!dtsPath || typeof dtsPath !== 'string') {
+          warnings.push('exports["./controller"].types is missing');
+        } else {
+          const abs = join(elementDir, dtsPath.replace(/^\.\//, ''));
+          if (!existsSync(abs)) {
+            warnings.push(`Controller d.ts artifact missing: ${dtsPath}`);
+          }
+        }
+      }
+
+      results.push({ element, ok: errors.length === 0, errors, warnings });
+    }
+
+    const failed = results.filter((r) => !r.ok);
+    const warned = results.filter((r) => r.warnings.length > 0);
+    const checked = results.filter((r) =>
+      hasAnyControllerSource(join(ELEMENTS_REACT_DIR, r.element))
+    );
+
+    this.log(`\n${'='.repeat(60)}`);
+    this.log('📊 CONTROLLER PUBLISH VERIFICATION REPORT');
+    this.log('='.repeat(60));
+    this.log(`Elements scanned:           ${results.length}`);
+    this.log(`Elements with controllers:  ${checked.length}`);
+    this.log(`Passed:                    ${results.length - failed.length} ✅`);
+    this.log(`Failed:                    ${failed.length} ❌`);
+    this.log(`Warnings:                  ${warned.length} ⚠️`);
+
+    if (failed.length > 0) {
+      this.log('\n❌ FAILURES:');
+      for (const f of failed) {
+        this.log(`  - ${f.element}`);
+        for (const e of f.errors) this.log(`    • ${e}`);
+      }
+      this.log('\n💡 Fixes:');
+      this.log('  - Ensure package.json exports include "./controller"');
+      this.log('  - Ensure build outputs exist under dist/controller/');
+      this.log(`  - Rebuild: cd ${ELEMENTS_REACT_DIR}/<element> && bun run build`);
+      this.error('Some controller publish checks failed', { exit: 1 });
+    }
+
+    if (warned.length > 0) {
+      this.log('\n⚠️  WARNINGS (non-blocking):');
+      for (const w of warned) {
+        this.log(`  - ${w.element}`);
+        for (const msg of w.warnings) this.log(`    • ${msg}`);
+      }
+    }
+
+    this.log(`\n${'='.repeat(60)}\n`);
+  }
+}

package/src/commands/verify/react-build.ts

@@ -0,0 +1,171 @@
+import { Command, Flags } from '@oclif/core';
+import { Logger } from '../../utils/logger.js';
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+interface BuildResult {
+  element: string;
+  success: boolean;
+  error?: string;
+  duration?: number;
+}
+
+const ELEMENTS_REACT_DIR = 'packages/elements-react';
+
+export default class ReactBuild extends Command {
+  static override description = 'Verify React element builds';
+
+  static override examples = ['<%= config.bin %> <%= command.id %>'];
+
+  static override flags = {
+    verbose: Flags.boolean({
+      char: 'v',
+      description: 'Show detailed build output',
+      default: false,
+    }),
+    element: Flags.string({
+      description: 'Build only specified element',
+    }),
+  };
+
+  private logger = new Logger();
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(ReactBuild);
+
+    this.logger = new Logger(flags.verbose);
+
+    this.logger.section('🔨 Verifying React element builds');
+
+    // Get all element directories
+    const items = await readdir(ELEMENTS_REACT_DIR, { withFileTypes: true });
+    let elements = items.filter((item) => item.isDirectory()).map((item) => item.name);
+
+    // Filter to specific element if requested
+    if (flags.element) {
+      if (!elements.includes(flags.element)) {
+        this.error(`Element '${flags.element}' not found in ${ELEMENTS_REACT_DIR}`);
+      }
+      elements = [flags.element];
+    }
+
+    if (elements.length === 0) {
+      this.logger.warn(`⚠️  No React elements found in ${ELEMENTS_REACT_DIR}/`);
+      return;
+    }
+
+    this.logger.info(`Found ${elements.length} element(s) to verify\n`);
+
+    const results: BuildResult[] = [];
+
+    // Build each element sequentially
+    for (const element of elements) {
+      process.stdout.write(`  Building ${element}... `);
+
+      const result = await this.buildElement(element, flags.verbose);
+      results.push(result);
+
+      if (result.success) {
+        console.log(`✅ (${result.duration}ms)`);
+      } else {
+        console.log('❌');
+      }
+    }
+
+    // Generate report
+    this.log(`\n${'='.repeat(60)}`);
+    this.log('📊 BUILD VERIFICATION REPORT');
+    this.log('='.repeat(60));
+
+    const successful = results.filter((r) => r.success);
+    const failed = results.filter((r) => !r.success);
+
+    this.log(`Total:      ${results.length}`);
+    this.log(`Passed:     ${successful.length} ✅`);
+    this.log(`Failed:     ${failed.length} ❌`);
+
+    if (successful.length > 0) {
+      this.log('\n✅ SUCCESSFUL BUILDS:');
+      successful.forEach((r) => {
+        this.log(`  - ${r.element} (${r.duration}ms)`);
+      });
+    }
+
+    if (failed.length > 0) {
+      this.log('\n❌ FAILED BUILDS:');
+      failed.forEach((r) => {
+        this.log(`\n  Element: ${r.element}`);
+        if (r.error) {
+          // Extract first few lines of error for summary
+          const errorLines = r.error.split('\n').slice(0, 10);
+          errorLines.forEach((line) => {
+            if (line.trim()) {
+              this.log(`    ${line}`);
+            }
+          });
+          if (r.error.split('\n').length > 10) {
+            this.log('    ... (truncated)');
+          }
+        }
+      });
+
+      this.log('\n💡 To see full error for a specific element:');
+      this.log('   cd packages/elements-react/<element-name>');
+      this.log('   bun run build');
+    }
+
+    this.log(`\n${'='.repeat(60)}\n`);
+
+    // Exit with error code if any builds failed
+    if (failed.length > 0) {
+      this.error('Some builds failed', { exit: 1 });
+    }
+  }
+
+  private async buildElement(element: string, verbose: boolean): Promise<BuildResult> {
+    const elementDir = join(ELEMENTS_REACT_DIR, element);
+    const packageJsonPath = join(elementDir, 'package.json');
+
+    // Skip if no package.json
+    if (!existsSync(packageJsonPath)) {
+      return {
+        element,
+        success: false,
+        error: 'No package.json found',
+      };
+    }
+
+    const startTime = Date.now();
+
+    try {
+      execSync('bun run build', {
+        cwd: elementDir,
+        stdio: verbose ? 'inherit' : 'pipe',
+        encoding: 'utf-8',
+      });
+
+      const duration = Date.now() - startTime;
+
+      return {
+        element,
+        success: true,
+        duration,
+      };
+    } catch (error: unknown) {
+      const duration = Date.now() - startTime;
+
+      // Extract error message from stderr
+      const err = error as { stderr?: Buffer; message?: string };
+      const stderr = err.stderr?.toString() || err.message || 'Unknown error';
+
+      return {
+        element,
+        success: false,
+        error: stderr,
+        duration,
+      };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/src/lib/mathquill/extension-generator.ts

@@ -0,0 +1,111 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Logger } from '../../utils/logger.js';
+
+/**
+ * Extension Loader Generator
+ *
+ * Generates the main extension loader that initializes MathQuill
+ * with all patches and extensions in the correct order.
+ */
+
+export function generateExtensionLoader(mathquillPath: string, logger: Logger): void {
+  const loaderPath = join(mathquillPath, 'src/extensions/index.ts');
+
+  const content = `/**
+ * MathQuill Extensions Loader
+ *
+ * Loads all extensions in the correct order:
+ * 1. Desmos base (via npm package)
+ * 2. Khan Academy patches
+ * 3. Learnosity features
+ * 4. PIE features
+ *
+ * Generated by: pie mathquill:migrate
+ * Date: ${new Date().toISOString().split('T')[0]}
+ *
+ * DO NOT EDIT MANUALLY - Regenerate with: pie mathquill:migrate
+ */
+
+import MathQuill from 'mathquill';
+import type { MathQuillInterface, MathFieldInterface } from 'mathquill';
+
+// Import Desmos MathQuill CSS
+import 'mathquill/build/mathquill.css';
+
+// Khan Academy patches
+import {
+  applyMobileKeyboardFixes,
+  applyI18nAriaSupport,
+} from './khan/index.js';
+
+// Learnosity features
+import {
+  addRecurringDecimal,
+  addNotSymbols,
+  applyEmptyMethod,
+} from './learnosity/index.js';
+
+// PIE features
+import {
+  addMatrixCommands,
+  addLRNExponent,
+} from './pie/index.js';
+
+// Import PIE matrix styles
+import './pie/styles.css';
+
+/**
+ * Initialize MathQuill with all extensions
+ *
+ * This creates a MathQuill instance (v3 interface) with:
+ * - Desmos base (TypeScript, modern)
+ * - Khan Academy mobile and accessibility patches
+ * - Learnosity educational features
+ * - PIE custom extensions
+ *
+ * @returns Initialized MathQuill interface
+ */
+export function initializeMathQuill(): MathQuillInterface {
+  // Get MathQuill v3 interface (no jQuery in public API)
+  const MQ = MathQuill.getInterface(3);
+
+  // Apply Khan Academy patches
+  applyMobileKeyboardFixes(MQ);
+  applyI18nAriaSupport(MQ);
+
+  // Add Learnosity features
+  addRecurringDecimal(MQ);
+  addNotSymbols(MQ);
+  applyEmptyMethod(MQ);
+
+  // Add PIE features
+  addMatrixCommands(MQ);
+  addLRNExponent(MQ);
+
+  return MQ;
+}
+
+// Create and export initialized instance
+const MQ = initializeMathQuill();
+
+// Default export: initialized MathQuill
+export default MQ;
+
+// Named exports
+export const getInterface = MathQuill.getInterface;
+export const MathField = MQ.MathField;
+export const StaticMath = MQ.StaticMath;
+
+// Re-export types
+export type {
+  MathQuillInterface,
+  MathFieldInterface,
+  StaticMathInterface,
+  MathFieldConfig,
+} from 'mathquill';
+`;
+
+  writeFileSync(loaderPath, content);
+  logger.success(`   ✓ Generated extension loader`);
+}