README.md

@pie-element/cli

CLI tools for managing PIE Elements NG - synchronization, package generation, and verification.

Installation

From the root of the monorepo:

bun install
cd tools/cli
bun run build

Usage

From the root of the monorepo:

# Show help
bun run cli --help

# Show command help
bun run cli upstream:sync --help

Commands

Development

dev:demo

Start a demo server for an element using apps/element-demo.

# Start demo for an element
bun run cli dev:demo hotspot

# Custom port, skip builds, and don't auto-open browser
bun run cli dev:demo multiple-choice --port 5180 --skip-build --no-open

Upstream Synchronization

upstream:sync

Synchronize code from upstream pie-elements repository.

# Dry run to preview changes
bun run cli upstream:sync --dry-run

# Sync specific element
bun run cli upstream:sync --element multiple-choice

# Sync all compatible elements (controllers + React UI + demos)
bun run cli upstream:sync

# Verbose output
bun run cli upstream:sync --verbose

upstream:check

Check for changes in upstream repositories.

# Check all elements
bun run cli upstream:check

# Check specific element
bun run cli upstream:check --element multiple-choice

# Verbose output
bun run cli upstream:check --verbose

upstream:track

Track upstream repository changes.

# Show new commits since last check
bun run cli upstream:track show

# Record current upstream state
bun run cli upstream:track record

# Compare with specific commit
bun run cli upstream:track compare <commit-sha>

upstream:deps

Compare dependencies with upstream repositories.

bun run cli upstream:deps

upstream:analyze-esm

Analyze ESM compatibility of elements and packages.

# Analyze and generate report
bun run cli upstream:analyze-esm

# Verbose output
bun run cli upstream:analyze-esm --verbose

# Custom output path
bun run cli upstream:analyze-esm --output ./my-report.json

upstream:update

Recommended wrapper that runs analyze + sync.

bun run cli upstream:update

Package Management

packages:enable-publishing

Enable publishing for all @pie-element/* and @pie-lib/* packages (remove private flags and clear matching Changesets ignore entries).

# Dry run
bun run cli packages:enable-publishing --dry-run

# Enable publishing
bun run cli packages:enable-publishing

packages:create-controllers

Generate package.json files for controller packages.

bun run cli packages:create-controllers

packages:create-lib-react

Generate configuration files for @pie-lib React packages.

# Dry run
bun run cli packages:create-lib-react --dry-run

# Generate files
bun run cli packages:create-lib-react

packages:create-react-elements

Generate configuration files for React element packages.

bun run cli packages:create-react-elements

packages:init-synced-elements

Initialize package scaffolding for synced elements.

bun run cli packages:init-synced-elements

Documentation

docs:generate

Generate framework-agnostic HTML docs artifacts for elements from per-element docs.contract.json descriptors. The element demo runs this during prebuild/predev; the generated static/element-docs directory is a local build artifact and is not committed.

# Generate docs for all elements
bun run cli docs:generate

# Generate for one framework/element
bun run cli docs:generate --framework svelte --element simple-cloze

# Seed missing contracts before generation
bun run cli docs:generate --seed-contracts

Verification

docs:verify

Verify that all targeted elements have valid docs.contract.json descriptors and that local generated docs match the current generator output.

# Verify all frameworks
bun run cli docs:verify

# Verify one framework/element
bun run cli docs:verify --framework svelte --element simple-cloze

verify:controllers

Verify controller package exports before publishing.

bun run cli verify:controllers

verify:react-build

Verify that all React elements build successfully.

bun run cli verify:react-build

verify:dependency-integrity

Inspect package imports and classify dependency usage as direct, transitive, hoist-reliant, or broken.

# Scan all element/lib-react packages
bun run cli verify:dependency-integrity

# Scan one package
bun run cli verify:dependency-integrity --package @pie-element/ebsr

# Fail on hoist-reliant imports too (not only broken)
bun run cli verify:dependency-integrity --fail-on-hoist

CLI Development

# Build the CLI
bun run build

# Run in development mode (with source maps)
bun run dev upstream:sync --help

# Lint
bun run lint

Architecture

The CLI is built with oclif, following the same architecture as the pie-qti CLI.

• Commands: Located in src/commands/ organized by topic
• Utilities: Shared utilities in src/utils/
• Topics: Commands are grouped into topics (upstream, packages, docs, verify)

Migration from Scripts

This CLI replaces the scripts in ./scripts directory:

Old Script	New CLI Command
bun scripts/sync-upstream.ts	bun run cli upstream:sync
bun scripts/check-upstream.ts	bun run cli upstream:check
bun scripts/track-upstream.ts show	bun run cli upstream:track show
bun scripts/check-deps.ts	bun run cli upstream:deps
bun scripts/analyze-esm-compatibility.ts	bun run cli upstream:analyze-esm
bun scripts/enable-react-publishing.ts	bun run cli packages:enable-publishing
bun scripts/create-controller-packages.ts	bun run cli packages:create-controllers
bun scripts/create-lib-react-packages.ts	bun run cli packages:create-lib-react
bun scripts/create-react-packages.ts	bun run cli packages:create-react-elements
bun scripts/verify-react-build.ts	bun run cli verify:react-build

License

Same as parent project.