pdx

AI-assisted Pega Constellation DX component toolchain. It scaffolds, validates, skins, and troubleshoots Pega Constellation DX components against the real PCore/PConnect API surface and DX Component Builder conventions.

Install & run anywhere

# from the registry (once published)
npx @pisbouts-byte/pdx-cli scaffold "a phone field for self service"

# straight from the git repo
npx --yes github:you/pdx-cli scaffold "a phone field for self service"

Requires only Node >= 20 and an internet connection. Deterministic commands (scaffold, validate, skin, troubleshoot) work with no API key; set ANTHROPIC_API_KEY and pass --llm to generate component code with an LLM.

A curated starter knowledge base is bundled, so scaffold retrieves Pega conventions immediately on a fresh machine. Run pdx ingest @default --render to replace it with live crawled docs.

Commands

| Command | Purpose | | --- | --- | | pdx ingest <source> | Build the knowledge base from Pega docs (URLs) or a local SDK / UI-gallery checkout. @default uses the curated doc seeds. --kind samples for a local checkout. | | pdx scaffold <requirement> | Decide the component type/subtype (Field, Widget, Layout template) from a natural-language requirement and generate config.json, index.tsx, Storybook story, and NOTES.md (with App Studio wiring instructions). | | pdx validate <dir> | Check config.json against the component-definition schema + conventions, structural-lint index.tsx, and optionally typecheck against a Constellation SDK checkout (--sdk <dir>). | | pdx skin <style.css> | Extract design tokens from a CSS/style guide and emit a theme + styled wrapper for a component. | | pdx troubleshoot "<symptom>" | Classify the issue and direct you to where in Pega to find/share logs plus proposed actions. |

Examples

# Ingest the default doc seeds into ./knowledge_base
npm run dev -- ingest @default

# Ingest a cloned SDK checkout as golden example source code
npm run dev -- ingest /path/to/constellation-ui-gallery --kind samples

# Scaffold a component
npm run dev -- scaffold "A URL field that launches a local action from a button" --type Field --subtype URL

# Validate it
npm run dev -- validate components/MyCo_MyComponents_MyLocalActionLauncher

# Skin it from a brand style sheet
npm run dev -- skin brand.css --component "My URL field"

# Triage a problem
npm run dev -- troubleshoot "component is not showing after publish"

Architecture

• src/knowledge/ - crawler (docs.pega.com), chunker, hashing-embedder placeholder, local vector store (chunks.json). Swap hashEmbed for a real embedding provider behind the same signature.
• src/scaffold/ - deterministic planner (type/subtype/properties decision) + generator. Golden-example catalog mirrors Pega's DXCB samples. A bundled starter KB (starterKnowledge.ts) is searched when the local store is empty. --llm routes generation through Anthropic (ANTHROPIC_API_KEY).
• src/validate/ - config.json schema/convention checks, index.tsx structural lint, optional SDK typecheck.
• src/skin/ - CSS token extraction + theme/wrapper generation. Wireframe (vision) analysis is stubbed.
• src/troubleshoot/ - keyword triage into build / publish / runtime / styling / data / auth with Pega-specific log pointers.

Roadmap

1. Real embedding provider + retrieval for scaffold
2. Multimodal wireframe analysis in skin
3. Publish/verify against a live Pega instance via the DX API
4. Richer golden-example index driven by ingest --kind samples

Publishing to npm

prepublishOnly typechecks + builds, and the published tarball ships only dist/ + README.md. Run npm login then npm publish. Requires the scope @pisbouts-byte (your npm username) — create the npm account if it doesn't exist.