@pega/custom-dx-components 26.1.11 → 26.1.12-alpha.0.2

package/src/ai/project/.claude/skills/update-dx-component/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: update-dx-component
+description: 'Change an EXISTING Pega DX component safely: add or change a behavior, add or remove an authoring property, fix a bug, restyle, change a stored-value format, or plan a rename, move, version bump or upgrade. Use when: the user asks to modify, extend, fix, refactor, rename or retire a component that already exists under src/components. For a brand-new component use the type skills instead.'
+argument-hint: 'Name the component and the change (for example "Acme_Lib_Quantity: add a step property")'
+---
+
+# Update an Existing DX Component
+
+A component that has been published may already be configured in views that people use. A change that looks small in code can break those views or the data they saved, so this skill is about understanding what exists, classifying the risk, and keeping every artifact in step.
+
+## Procedure
+
+### 1. Understand what exists
+
+- Read the whole folder `src/components/<Org>_<Library>_<Name>/`: `config.json`, `index.tsx` and helpers, `styles.ts`, `mock.ts`, `demo.stories.tsx`, `demo.test.tsx`, `localizations.json` if present.
+- Write down the current contract in a few lines: the type and subtype, the authoring properties and their defaults, the value or data it handles, the states it covers. If a brief or the original request is available, compare it with the code and note any difference.
+- Run `node .claude/skills/validate-component/scripts/check-component.mjs <key> --no-build` first. This is the baseline. Failures that were already there are not yours to hide or to fix unasked; report them.
+
+### 2. Classify the change
+
+Use the lists in the "Safe and risky changes" section of [config-schema.md](../create-dx-component/references/config-schema.md).
+
+| Class | Examples | What to do |
+| --- | --- | --- |
+| Safe | A bug fix with no contract change; styling; an optional property with a backward-compatible default; a new state; better tests | Make it, keeping all artifacts in sync |
+| Behavior change | Different validation, a different commit moment, new display rules | Tell the user what existing users will see change, then make it |
+| Risky | Renaming or removing a property, region or option key; changing the type or shape of a stored value; changing a default so existing components behave differently; changing a picker from scalars to objects; hiding a property that was editable | Stop. Describe the effect on views and data already saved and propose a compatible alternative (add the new shape, keep the old one). Proceed only when the user chooses |
+| Different component | A different type or subtype; a different stored value type | The subtype cannot change in place. Propose a new component and retiring the old one |
+| Structural | Rename, move, copy, delete, switch library or version | These are the user's commands. See [maintenance.md](./references/maintenance.md); do not run them unasked |
+
+When in doubt, treat the change as risky and ask once.
+
+### 3. Plan before editing
+
+State, in one message, what will change in each artifact, the class from step 2, how absent and legacy values behave (what a view saved before the change will do), and what the user must do afterwards (publish, retest). Wait for approval for anything above Safe.
+
+### 4. Make the change
+
+- Change `config.json`, `index.tsx`, `styles.ts`, `mock.ts`, the stories and the tests **together**. Every property in `config.json` must still be read by the code, with a safe default for an absent value.
+- Keep the diff small. Do not refactor unrelated code, rename scaffold-owned names, or upgrade dependencies as a side effect.
+- Follow the same rules as for a new component: Cosmos first, no inline styles, no new third-party library without consent, only documented PCore and PConnect methods. Read the references that match the type: [field-behavior.md](../create-dx-component/references/field-behavior.md), [widget-patterns.md](../create-dx-component/references/widget-patterns.md) or [template-patterns.md](../create-dx-component/references/template-patterns.md).
+- Do not delete or weaken an existing test to make a change pass. If an intentional change makes a test wrong, update it and say why.
+
+### 5. Prove it
+
+- Add tests for the new behavior, and one test for the legacy case (an absent or old value renders as before).
+- Run `node .claude/skills/validate-component/scripts/check-component.mjs <key>` and paste the table into the report, as for a new component.
+- For anything above Safe, run the [review-component](../review-component/SKILL.md) skill.
+
+### 6. Report
+
+Say what changed in each file, the class of the change, who or what is affected (views already using the component, saved data), and what you could not verify. Remind the user that the change reaches Pega only after they publish (a user-run step) and that it should be retested in App Studio.
+
+## Version numbers
+
+The `version` in `config.json` is a label for this component. Whether to bump it, and whether to create a new library version, is the user's decision: ask, and explain that a published library version is what Pega loads. Do not run `createLibVersion`, `publish` or any other server or structural command unasked.

package/src/ai/project/.claude/skills/update-dx-component/references/maintenance.md

@@ -0,0 +1,43 @@
+# Maintenance, Renames, Versions and Upgrades
+
+What a customer owns after the first publish, and the commands that exist for it. Every command here is the user's to run unless they explicitly ask you to; they need credentials, a server, or change or delete data. The exact forms are in [cli-workflow.md](../../create-dx-component/references/cli-workflow.md) and [publish-library](../../publish-library/SKILL.md).
+
+## What the customer owns
+
+The CLI prints this on its help screen, and it should be said plainly to anyone building custom components: by choosing to create and use custom components, you agree to keep them up to date with every release of Pega Infinity, and to meet compliance standards for data privacy and accessibility. Pega does not update a custom component for you.
+
+## Rename, move and delete
+
+| Goal | Command | Effect and caution |
+| --- | --- | --- |
+| Rename a component | `npm run rename` | Changes the component key, which is the component's persisted identity. A view that references the old key is likely to stop finding it, so treat a rename of a published component as a breaking change and ask the user first. Prefer a new component with the new name and retire the old one later |
+| Move or copy a component (or all) to another version or library | `npm run move` | Check the target library and version with the user first |
+| Delete a component | `npm run delete` | Destructive. Confirm which one, and that no view still uses it |
+| Delete everything | `npm run deleteAll`, `npm run deleteLib`, `npm run deleteLibVersion`, `npm run deletePublishedLib` | Destructive and often permanent. Never run unasked |
+
+## Library versions
+
+| Goal | Command | Note |
+| --- | --- | --- |
+| See the current library, version and component count | `npm run showStatus` | Safe |
+| List the contents of a library or version | `npm run listLib`, `npm run list` | `listLib` prompts and cannot run without a terminal |
+| Start a new version | `npm run createLibVersion` | Ask the user first |
+| Switch version or library | `npm run switchLibVersion`, `npm run switchLib` | Changes which version later commands act on |
+| Save a version locally | `npm run storeLibVersion` | Save components before storing |
+| Go back to the stored copy | `npm run restoreLibVersion` | The CLI warns that current changes will be **lost**. Never run unasked |
+| Export or import a version as a zip | `npm run exportLibVersion`, `npm run importLibVersion` | |
+| Publish | `npm run publish` | See [publish-library](../../publish-library/SKILL.md) |
+
+## Upgrading
+
+- **The CLI.** `npm run upgrade` reinstalls `@pega/custom-dx-components` at the latest version. It changes the project's dependencies, so ask first, then run the check script for every component and `npm run validateAll`.
+- **Pega Infinity.** After the customer's Infinity version changes, republish and retest the components in App Studio. Check the Pega documentation for the new release for anything that affects custom components, and tell the user what you could not verify.
+- **Cosmos.** Components are built against the installed `@pega/cosmos-react-core`. When it changes, a prop can be added, renamed or removed. After any dependency change run `npx tsc --noEmit`, the check script and the Storybook states, and read the `.d.ts` of any Cosmos component that now fails to compile instead of guessing the new prop.
+- **AI skills.** `npm run enableAi` restores missing skill files but never overwrites an existing one, so installed skills do not update themselves. If the guidance feels out of date, ask the user to compare `.claude/skills` with the version that ships in the installed CLI package.
+
+## Before any structural change
+
+1. Run `npm run showStatus` and `npm run list` to see the current library, version and components.
+2. Say exactly what the command will change and what cannot be undone.
+3. Make sure local work is saved, for example with `npm run storeLibVersion`, if the command can lose it.
+4. Let the user run the command, or run it only when they ask.

package/src/ai/project/.claude/skills/url/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: url
+description: 'Scaffold a Pega DX Field component with subtype **URL** — web address input bound to a string case property. Use when: user asks for a URL input, website link field, external reference, or a clickable link display.'
+argument-hint: 'Describe the URL field (e.g., "a company website input that opens in a new tab")'
+---
+
+# Create URL Field
+
+Field subtype `URL`. Binds to a string case property holding a web address.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `URL`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit | `Input` with `type='url'` from `@pega/cosmos-react-core` |
+| `DISPLAY_ONLY` | `URLDisplay` |
+
+## Value Handling
+
+- Trim on blur and prepend `https://` when the user omitted a scheme, then dispatch the normalized value.
+- Validate the scheme before storing. **Only `http:` and `https:` are acceptable.**
+  Parse the value with `new URL(raw)` inside a try/catch, and accept it only when the protocol is `http:` or `https:`. A value that does not parse is unsafe. The helper shape is in [field-behavior.md](../create-dx-component/references/field-behavior.md).
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `openInNewTab` | Open in a new tab | `BOOLEAN` | `true` |  |
+| `linkText` | Link text override | `TEXT` |  |  |
+
+## Security
+
+This is the highest-risk Field subtype in the set.
+
+- **Reject `javascript:`, `data:`, `vbscript:`, and `file:` schemes.** Rendering an unchecked user-supplied URL in an `href` is a stored XSS vector.
+- Do not assume `URLDisplay` makes a value safe. In the Cosmos build checked, its `Link` only drops hrefs that match `javascript:`; `data:`, `vbscript:` and `file:` pass through, and it sets no `rel` on the anchor. Run the allow-list check above on the value before rendering, and verify the behavior against the installed Cosmos version.
+- When `openInNewTab` is on, set `rel='noopener noreferrer'` yourself unless you have confirmed the rendered anchor already has it.
+- Cosmos exports `disallowedURI` (a regex) in some builds; if it exists in the installed version you may use it as an extra check, but keep the explicit protocol allow-list.
+- Never interpolate the value into `dangerouslySetInnerHTML`.
+- Production URL fields commit the raw string on blur and do no scheme check, so the scheme rule above is **your** responsibility, not the platform's.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/validate-component/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: validate-component
+description: 'Build, validate, test, lint, and publish workflow for Pega DX components in this repo. Use for running npm run validate, diagnosing build or Storybook failures, fixing Jest coverage gaps, resolving lint and spelling errors, and publishing a component or library version.'
+argument-hint: 'validate, test, lint, storybook, fix, or publish'
+---
+
+# Validate Component Workflow
+
+Use this skill when the task is about the build and release loop for an existing component, rather than authoring a new one. For authoring, use the `create-*-component` skills.
+
+## One-command check (use this first)
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` from the project root. It runs the schema check, `tsc` (scoped to this component and incremental), ESLint and Jest in parallel, checks that every `config.json` property is actually read by the code, warns about formats the CLI scaffolds do not use, flags inline styles, raw HTML injection and secrets, warns when there is only one story or one test, and runs the build once the schema and ESLint checks pass. It prints a table of PASS, FAIL, WARN and NOT RUN, and exits 1 if anything failed. While fixing failures, add `--no-build` to skip the slow bundle; run it once without the flag for the final table.
+
+Paste the table into your final report. Report a check as passing only when the table says PASS; a `NOT RUN` or `FAIL` row must be stated as such, with the reason. Use the individual commands below to iterate on a failure, then rerun the script for the final table. Do not weaken a check to turn a row green.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run validate -- <Org>_<Library>_<Name> N N` | Validate the schema, lint and bundle one component (`custom-dx-components buildComponent <key> <sourceMap> <devBuild>`). **Without arguments it prompts interactively and hangs an agent** |
+| `npm run validate-schema -- <Org>_<Library>_<Name>` | Check only `config.json` against the schema |
+| `npm run validateAll` | Build all components (no prompts) |
+| `npx tsc --noEmit 2>&1 \| grep -v demo.stories.tsx` | Type-check your own files; scaffolded stories report known `window.PCore` noise |
+| `npx jest <folder> --coverage=false` | Run one component's tests without the coverage gate |
+| `npm run test` | Run Jest with coverage |
+| `npm run coverage` | Run Jest and emit an HTML coverage report |
+| `npm run lint` | Run ESLint |
+| `npm run _lint:types` | Type-check with `tsc --noEmit` |
+| `npm run _lint:format` | Prettier check |
+| `npm run _lint:spelling` | cspell check |
+| `npm run _lint:styles` | Stylelint check |
+| `npm run startStorybook` | Storybook dev server on port 6040 |
+| `npm run publish` | Publish to the configured Pega server |
+| `npm run authenticate` | Refresh server credentials before publishing |
+
+## Coverage Thresholds
+
+From `jest.config.cjs`, the global gate is statements 79, branches 74, functions 81, lines 80. A component that drops the global number below these fails the run even when its own tests pass.
+
+## Procedure
+
+1. Identify the component folder under `src/components/<Org>_<Library>_<Name>/`; the folder name is the component key.
+2. Run `npm run validate -- <Org>_<Library>_<Name> N N` first (or `npm run validate-schema -- <Org>_<Library>_<Name>` for the schema alone). It surfaces schema and build errors faster than the test suite. The full check loop is in [../create-dx-component/references/cli-workflow.md](../create-dx-component/references/cli-workflow.md).
+3. If `config.json` fails, check it against the schema reference in [../create-dx-component/references/config-schema.md](../create-dx-component/references/config-schema.md). Property `format` values must come from the supported list.
+4. Run `npm run test`. If coverage fails, add cases for the untested branches rather than lowering the threshold.
+5. Run `npm run lint` and `npm run _lint:types`. Fix unused imports, unused state, and unused interface fields, since dead code is a policy violation in this repo.
+6. Run `npm run startStorybook` for a visual check when the change affects rendering.
+7. Publishing is out of scope for this skill — use [../publish-library/SKILL.md](../publish-library/SKILL.md).
+
+## After the build is green
+
+If the component builds but misbehaves in App Studio or a real view (not offered in the picker, wrong property panel, blank render, differs from Storybook), use [runtime-troubleshooting.md](./references/runtime-troubleshooting.md). It is a diagnostic ladder that asks the user for evidence at each step.
+
+## Common Failures
+
+- **Missing `create-nonce` import** — styled-components fail CSP in the Pega host. Every component that uses `styled-components` must side-effect import `../shared/create-nonce`.
+- **Missing `withConfiguration()`** — the component will not register with Constellation.
+- **`PCore is not defined` in tests** — the Storybook file must assign `window.PCore` before the story renders.
+- **Story not composing** — `demo.test.tsx` uses `composeStories`, so the export name in `demo.stories.tsx` must match the destructured name.
+- **Type errors on `PConnProps`** — confirm the component folder has its own `PConnProps.d.ts` copied from the shared asset.
+- **cspell failures** — add genuine domain terms to `cspell.json` rather than renaming identifiers.
+- **`Highlight is not defined` / `X.animate is not a function` from inside `node_modules`** — jsdom is missing a browser API that Cosmos calls at module scope. Add the stub to [../../../setupTests.ts](../../../setupTests.ts); do not work around it in the component.
+- **`messages.flatMap is not a function`** — `Banner` `messages` takes an array, not a string.
+- **A Cosmos prop appears to do nothing** — it is probably not a real prop. Read `node_modules/@pega/cosmos-react-core/lib/components/<Name>/<Name>.d.ts`; `EmptyState` uses `message` not `title`, and `Tag` uses `children` not `label`.
+- **`Cannot read properties of undefined (reading 'palette')` in `styles.ts`** — Cosmos ships a nested `styled-components`, so its theme never reaches your `styles.ts`. Call `useTheme()` in `index.tsx` and pass the values as props.
+- **`npm run validate` prompts for input, or says "Please create/import a library"** — pass the component key and `N N` (`npm run validate -- <Org>_<Library>_<Name> N N`); if a library is missing, run `npm run createLib -- <Library> 1.0.0 Y Current` first (see [../publish-library/SKILL.md](../publish-library/SKILL.md)).
+- **Coverage prints `0%`** — expected. `collectCoverageFrom` in [../../../jest.config.cjs](../../../jest.config.cjs) is scoped to the CLI's own source, so component code is never instrumented. Do not chase the number; still cover every branch you wrote.
+
+## Output Format
+
+When responding, prefer this order:
+
+1. What was run and the result.
+2. The specific failure, quoted from the output.
+3. The root cause.
+4. The fix applied, or the exact fix to apply.
+5. The follow-up command to confirm the fix.

package/src/ai/project/.claude/skills/validate-component/references/runtime-troubleshooting.md

@@ -0,0 +1,56 @@
+# Troubleshooting a Component After It Builds
+
+For problems that appear after `check-component` is green: the component is not offered in App Studio, its property panel is wrong, it renders blank or wrongly in a real view, or it behaves differently from Storybook. Work down the ladder, **ask the user for the evidence in each rung instead of guessing**, and say what you could not check. You usually cannot see the Pega server, so never claim that something works or fails there without evidence from the user.
+
+## 0. Get the facts first
+
+Ask for, or look up:
+
+- The exact symptom and where it appears (App Studio picker, property panel, a case view, a portal page).
+- The text of any error in the browser console, and what the page shows instead (nothing, a generic failure message, the old version).
+- `npm run showStatus` output (library, version, permanence, component count) and whether the component was published, and to which server and ruleset.
+- The Pega Infinity version and the `@pega/cosmos-react-core` version in `package.json`.
+- Whether Storybook shows the component correctly in the same state.
+
+## 1. It is not offered in App Studio
+
+| Check | How |
+| --- | --- |
+| It was published, from the right library and version | `npm run showStatus` and `npm run listPublishedLib` (local or server). Publishing is the user's step |
+| The `type` and `subtype` suit the placement | A Field appears where fields are picked, a Template where layouts are picked, a Widget in a case view (`CASE`) or on a page (`PAGE`). A wrong subtype is a different placement, not an error. Compare against [choosing-type-and-subtype.md](../../create-dx-component/references/choosing-type-and-subtype.md) |
+| The component key matches what was published | The key is `<Org>_<Library>_<Name>` and must agree in `config.json`, the folder and `tasks.config.json` (library mode enforces library and organization) |
+| The user is looking in the right application and ruleset | These are server settings in `tasks.config.json` (`rulesetName`, `rulesetVersion`). Ask; do not change them |
+
+## 2. The property panel is wrong or empty
+
+- `validate-schema` only checks that `format` is a string. A format the platform does not support passes and then does nothing in App Studio. Read the `check-component` table for the formats warning, and compare with [config-schema.md](../../create-dx-component/references/config-schema.md).
+- A `visibility` expression that references a variable the authoring runtime does not provide hides the property. Use only the forms listed in config-schema.md.
+- A property whose `name` is not read by the component has no effect; `check-component` fails on that.
+- A property saved before a change can leave an old value behind. See [update-dx-component](../../update-dx-component/SKILL.md).
+
+## 3. It renders blank, or shows a generic failure message
+
+The platform wraps every component in an error boundary, so a component that throws shows a generic failure message instead of crashing the page. The real error is in the browser console.
+
+| Likely cause | Evidence and fix |
+| --- | --- |
+| An exception in render, often reading a property of `undefined` | The console stack trace names the file. Guard the absent value. Typical sources: a prop that arrives `null`, `children` treated as fields (they are regions), a missing optional config key |
+| Missing `withConfiguration()` | The component does not register. Check the export |
+| Missing `create-nonce` import | styled-components styles are blocked by the page's content security policy, so the component renders unstyled or broken. Keep the side-effect import in `index.tsx` |
+| A prop arrives as a string when you expected a boolean or a number | `readOnly`, `required`, `disabled` and numeric settings can arrive as strings. Normalize them (see [field-behavior.md](../../create-dx-component/references/field-behavior.md)) |
+| `PCore` or `getPConnect` used in a Presentation component | Not available there; the lint rule rejects it |
+| A PCore or PConnect method that is not documented | It may not exist in the user's Infinity version. Check the API catalog |
+
+## 4. It works in Storybook but not in a real view
+
+Storybook uses the mocks you wrote. The usual causes are a mock that differs from the real payload shape, a platform value that is `null` or a string in real data, and a data page or property that the real application does not have. Ask the user for the real payload (with any customer data removed), compare it with `mock.ts`, and fix the component and the mock together.
+
+To debug against the running platform with browser breakpoints, the CLI has `npm run startDevServer` ("debug runtime with browser break points using a local component server"; library mode). It is a long-running server, so the user runs it. Ask them to set a breakpoint where the console error occurs and report what they see.
+
+## 5. It shows an old version
+
+Confirm with the user that the new version was published and that they refreshed the application. Check `npm run showStatus` for the library version and whether it is permanent. Do not guess at server-side caching; say that you cannot see it and ask the user to check with their Pega administrator.
+
+## 6. Still stuck
+
+Summarize what was checked and what each check showed, list what you could not see, and tell the user exactly what to bring to Pega support or their administrator: component key, Infinity version, Cosmos version, the console error, and the `showStatus` output. Never include credentials, tokens or customer data.

package/src/ai/project/.claude/skills/validate-component/scripts/check-component.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// Runs every check a finished DX component needs and prints an evidence table.
+//   node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name> [--no-build]
+// Each check ends as PASS, FAIL, WARN or NOT RUN. Paste the table into the final report; never claim a check that
+// the table does not show as PASS. Exit code 1 means at least one FAIL.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+// The 17 formats the CLI scaffolds use. Other formats pass validate-schema (it only checks that format is a string)
+// but are not proven to work for custom components.
+export const SCAFFOLD_FORMATS = new Set([
+  'GROUP',
+  'TEXT',
+  'SELECT',
+  'NUMBER',
+  'BOOLEAN',
+  'VISIBILITY',
+  'REQUIRED',
+  'DISABLED',
+  'READONLY',
+  'VALUEINPUT',
+  'LABEL',
+  'CONTENTPICKER',
+  'CASCADE',
+  'PROPERTY',
+  'INLINE',
+  'DATASOURCE',
+  'INSTRUCTIONS',
+]);
+
+// Formats whose value the platform consumes itself, so the component code does not need to read the property.
+const PLATFORM_HANDLED = new Set(['VISIBILITY', 'REQUIRED', 'DISABLED', 'READONLY', 'CONTENTPICKER', 'INSTRUCTIONS', 'LABEL', 'INLINE']);
+
+const SECRET_PATTERNS = [
+  [/client[_-]?secret\s*[:=]\s*['"][^'"]+['"]/i, 'client secret'],
+  [/(password|passwd)\s*[:=]\s*['"][^'"]+['"]/i, 'password'],
+  [/bearer\s+[a-z0-9._-]{16,}/i, 'bearer token'],
+  [/(api[_-]?key|access[_-]?token)\s*[:=]\s*['"][^'"]{8,}['"]/i, 'API key or token'],
+  [/https?:\/\/[^\s'"]*\.(pegalabs|pega)\.[a-z.]+\/prweb/i, 'environment URL'],
+];
+
+const stripComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+
+/** Collect every property that carries a name, descending into groups and cascade sources. */
+export const collectProperties = (properties = []) =>
+  properties.flatMap((property) => {
+    const own = property.name ? [property] : [];
+    return [
+      ...own,
+      ...collectProperties(property.properties),
+      ...(property.source && !Array.isArray(property.source) ? collectProperties([property.source]) : []),
+    ];
+  });
+
+/** Names declared in config.json that the component code never mentions. */
+export const unconsumedProperties = (config, code) =>
+  collectProperties(config.properties)
+    .filter((property) => !PLATFORM_HANDLED.has(property.format))
+    .map((property) => property.name)
+    .filter((name) => !new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(code));
+
+/** Top-level authoring properties a story should expose as controls; DATASOURCE sub-fields are not props. */
+export const controllableProperties = (properties = []) =>
+  properties.flatMap((property) => {
+    if (property.format === 'GROUP') return controllableProperties(property.properties);
+    return property.name && !PLATFORM_HANDLED.has(property.format) ? [property.name] : [];
+  });
+
+/** Direct keys of the meta's argTypes object; nested settings, strings and comments are ignored. */
+const argTypesKeys = (source) => {
+  const code = stripComments(source);
+  const start = code.search(/\bargTypes\s*:\s*\{/);
+  if (start < 0) return new Set();
+  const keys = new Set();
+  let depth = 0;
+  let expectKey = false;
+  let index = code.indexOf('{', start);
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "'" || char === '"' || char === '`') {
+      let end = index + 1;
+      while (end < code.length && code[end] !== char) end += code[end] === '\\' ? 2 : 1;
+      if (depth === 1 && expectKey && char !== '`' && /^\s*:/.test(code.slice(end + 1))) keys.add(code.slice(index + 1, end));
+      expectKey = false;
+      index = end + 1;
+    } else if (/[A-Za-z_$]/.test(char)) {
+      const word = /^[\w$]+/.exec(code.slice(index))[0];
+      if (depth === 1 && expectKey && /^\s*:/.test(code.slice(index + word.length))) keys.add(word);
+      expectKey = false;
+      index += word.length;
+    } else {
+      if (char === '{' || char === '[' || char === '(') {
+        depth += 1;
+        expectKey = depth === 1 && char === '{';
+      } else if (char === '}' || char === ']' || char === ')') {
+        depth -= 1;
+        if (depth === 0) break;
+      } else if (char === ',') expectKey = depth === 1;
+      else if (!/\s/.test(char)) expectKey = false;
+      index += 1;
+    }
+  }
+  return keys;
+};
+
+/** Authoring properties with no entry in the story meta's argTypes. */
+export const missingStoryControls = (config, storySource) => {
+  const keys = argTypesKeys(storySource);
+  return controllableProperties(config.properties).filter((name) => !keys.has(name));
+};
+
+export const unprovenFormats = (config) => {
+  const formats = new Set();
+  const walk = (properties = []) =>
+    properties.forEach((property) => {
+      if (property.format) formats.add(property.format);
+      walk(property.properties);
+      if (property.source && !Array.isArray(property.source)) walk([property.source]);
+    });
+  walk(config.properties);
+  return [...formats].filter((format) => !SCAFFOLD_FORMATS.has(format)).sort();
+};
+
+export const findSecrets = (code) => SECRET_PATTERNS.filter(([pattern]) => pattern.test(stripComments(code))).map(([, label]) => label);
+
+export const countTests = (testSource) => (testSource.match(/\b(it|test)(\.each)?\s*\(/g) || []).length;
+export const countStories = (storySource) => (storySource.match(/export\s+const\s+\w+/g) || []).length;
+
+// The commands are independent, so they run in parallel; spawnSync would serialize them.
+const run = (command, args, { timeout = 600000, ...options } = {}) =>
+  new Promise((resolve) => {
+    let output = '';
+    let settled = false;
+    let timer;
+    const finish = (status, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ status, output, error });
+    };
+    const isWindows = process.platform === 'win32';
+    const child = spawn(command, args, { shell: false, detached: !isWindows, ...options });
+    const killTree = () => {
+      try {
+        if (isWindows) spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+        else process.kill(-child.pid, 'SIGKILL');
+      } catch {
+        child.kill('SIGKILL');
+      }
+    };
+    timer = setTimeout(() => {
+      output += `\nTimed out after ${timeout / 1000}s`;
+      killTree();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      finish(null);
+    }, timeout);
+    child.stdout?.on('data', (chunk) => (output += chunk));
+    child.stderr?.on('data', (chunk) => (output += chunk));
+    child.on('error', (error) => finish(null, error));
+    child.on('close', (status) => finish(status));
+  });
+
+// Type-check only this component, the shared folder and the global declarations instead of the whole project
+// (the project tsconfig also covers built output and every other component). Incremental, so re-runs are fast.
+const scopedTsconfig = (key, cwd) => {
+  try {
+    const cacheDir = path.join(cwd, 'node_modules', '.cache', 'dxcb-check');
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const fromCache = (target) => path.relative(cacheDir, path.join(cwd, target)).split(path.sep).join('/');
+    const file = path.join(cacheDir, `tsconfig.${key}.json`);
+    const tsconfig = {
+      extends: fromCache('tsconfig.json'),
+      include: ['src/*.d.ts', 'setupTests.ts', 'setupFiles.ts', `src/components/${key}/**/*`, 'src/components/shared/**/*'].map(fromCache),
+      compilerOptions: { noEmit: true, incremental: true, tsBuildInfoFile: `./${key}.tsbuildinfo` },
+    };
+    fs.writeFileSync(file, `${JSON.stringify(tsconfig, null, 2)}\n`);
+    return file;
+  } catch {
+    return undefined;
+  }
+};
+
+const tail = (text, lines = 6) => text.trim().split('\n').slice(-lines).join('\n');
+
+const check = (name, status, detail = '') => ({ name, status, detail });
+
+export const runChecks = async (key, { build = true, cwd = process.cwd(), env = process.env } = {}) => {
+  const results = [];
+  const folder = path.join(cwd, 'src', 'components', key);
+  if (!fs.existsSync(folder)) return [check('component folder', 'FAIL', `src/components/${key} does not exist`)];
+  results.push(check('component folder', 'PASS', `src/components/${key}`));
+
+  const tsconfig = fs.existsSync(path.join(cwd, 'tsconfig.json')) ? scopedTsconfig(key, cwd) : undefined;
+  const pending = {
+    schema: run('npm', ['run', 'validate-schema', '--', key], { cwd, env }),
+    tsc: run('npx', tsconfig ? ['tsc', '-p', tsconfig] : ['tsc', '--noEmit'], { cwd, env }),
+    lint: run('npx', ['eslint', `src/components/${key}`], { cwd, env }),
+    jest: run('npx', ['jest', `src/components/${key}`, '--coverage=false'], { cwd, env }),
+  };
+
+  const read = (file) => (fs.existsSync(path.join(folder, file)) ? fs.readFileSync(path.join(folder, file), 'utf8') : '');
+  const sourceFiles = fs
+    .readdirSync(folder)
+    .filter(
+      (file) =>
+        /\.(ts|tsx)$/.test(file) && !/^demo\./.test(file) && file !== 'mock.ts' && !file.endsWith('.d.ts') && !/\.(test|stories)\./.test(file),
+    );
+  const code = sourceFiles.map(read).join('\n');
+
+  const schema = await pending.schema;
+  const schemaPassed = schema.status === 0 && /valid/i.test(schema.output);
+  results.push(check('config.json schema', schemaPassed ? 'PASS' : 'FAIL', tail(schema.output, 3)));
+
+  let config = {};
+  try {
+    config = JSON.parse(read('config.json'));
+  } catch (error) {
+    results.push(check('config.json parses', 'FAIL', String(error.message)));
+  }
+
+  const formats = unprovenFormats(config);
+  results.push(
+    check(
+      'formats are scaffold-proven',
+      formats.length ? 'WARN' : 'PASS',
+      formats.length ? `not proven for custom components: ${formats.join(', ')}` : 'all formats are used by the CLI scaffolds',
+    ),
+  );
+
+  const missing = unconsumedProperties(config, code);
+  results.push(
+    check(
+      'config properties are consumed',
+      missing.length ? 'FAIL' : 'PASS',
+      missing.length ? `never referenced in the component: ${missing.join(', ')}` : 'every authoring property is read by the code',
+    ),
+  );
+
+  const lint = await pending.lint;
+  const lintPassed = lint.status === 0;
+
+  // `npm run validate` checks the schema and lints before it bundles and stops at the first failure, so it cannot
+  // pass while either of those fails. Start it as soon as both pass, alongside tsc and Jest.
+  let built;
+  if (build && schemaPassed && lintPassed) built = run('npm', ['run', 'validate', '--', key, 'N', 'N'], { cwd, env, timeout: 900000 });
+
+  const tsc = await pending.tsc;
+  const tscErrors = tsc.output
+    .split('\n')
+    .filter((line) => line.includes(`src/components/${key}/`) && line.includes('error TS') && !line.includes('demo.stories'));
+  // Errors with no file (a broken tsconfig, nothing to compile) would otherwise pass unnoticed.
+  const tscGlobalErrors = tsc.output.split('\n').filter((line) => /^error TS\d+/.test(line));
+  const tscProblems = [...tscErrors, ...tscGlobalErrors, ...(tsc.error ? [String(tsc.error.message)] : [])];
+  results.push(check('tsc (component files)', tscProblems.length ? 'FAIL' : 'PASS', tscProblems.slice(0, 5).join('\n')));
+
+  results.push(check('eslint', lintPassed ? 'PASS' : 'FAIL', lintPassed ? '' : tail(lint.output, 8)));
+
+  const jest = await pending.jest;
+  const summary = jest.output.match(/Tests:\s+(.*)/);
+  results.push(check('jest', jest.status === 0 ? 'PASS' : 'FAIL', summary ? summary[1] : tail(jest.output, 5)));
+
+  const tests = countTests(read('demo.test.tsx'));
+  results.push(
+    check('tests beyond the scaffold', tests > 1 ? 'PASS' : 'WARN', `${tests} test(s) in demo.test.tsx; cover each state in state-matrix.md`),
+  );
+
+  const stories = countStories(read('demo.stories.tsx'));
+  results.push(
+    check('stories per state', stories > 1 ? 'PASS' : 'WARN', `${stories} story export(s) in demo.stories.tsx; one story per applicable state`),
+  );
+
+  const noControls = missingStoryControls(config, read('demo.stories.tsx'));
+  results.push(
+    check(
+      'story controls',
+      noControls.length ? 'WARN' : 'PASS',
+      noControls.length ? `no argTypes entry in demo.stories.tsx for: ${noControls.join(', ')}` : 'every authoring property has a story control',
+    ),
+  );
+
+  const inlineStyle = /style=\{\{/.test(code);
+  const dangerous = /dangerouslySetInnerHTML/.test(code);
+  results.push(check('no inline styles', inlineStyle ? 'FAIL' : 'PASS', inlineStyle ? 'style={{ ... }} found; use Cosmos props or styles.ts' : ''));
+  results.push(check('no dangerouslySetInnerHTML', dangerous ? 'FAIL' : 'PASS', dangerous ? 'raw HTML injection found' : ''));
+
+  const secrets = findSecrets(`${code}\n${read('config.json')}\n${read('mock.ts')}`);
+  results.push(check('no secrets or environment URLs', secrets.length ? 'FAIL' : 'PASS', secrets.length ? `found: ${secrets.join(', ')}` : ''));
+
+  if (built) {
+    const result = await built;
+    const failed = result.status !== 0 || /FAILED|Error while|TypeError/.test(result.output);
+    results.push(check('build (lint, schema, bundle)', failed ? 'FAIL' : 'PASS', failed ? tail(result.output, 6) : ''));
+  } else if (build) {
+    results.push(check('build (lint, schema, bundle)', 'NOT RUN', 'skipped because the schema or ESLint check failed; fix those first'));
+  } else {
+    results.push(check('build (lint, schema, bundle)', 'NOT RUN', 'skipped with --no-build'));
+  }
+  return results;
+};
+
+export const formatReport = (key, results) => {
+  const count = (status) => results.filter((result) => result.status === status).length;
+  const lines = [`Check report for ${key}`, '', '| Check | Result | Detail |', '| --- | --- | --- |'];
+  results.forEach(({ name, status, detail }) =>
+    lines.push(`| ${name} | ${status} | ${detail.split('\n').join(' ').slice(0, 200).replace(/\|/g, '\\|')} |`),
+  );
+  lines.push('', `RESULT: ${count('PASS')} passed, ${count('FAIL')} failed, ${count('WARN')} warnings, ${count('NOT RUN')} not run`);
+  if (count('FAIL')) lines.push('Do not report this component as done until every FAIL is fixed or explained to the user.');
+  return lines.join('\n');
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  const key = args.find((arg) => !arg.startsWith('--'));
+  if (!key || !/^[A-Za-z0-9]+_[A-Za-z0-9]+_[A-Za-z0-9]+$/.test(key)) {
+    console.error('Usage: node check-component.mjs <Org>_<Library>_<Name> [--no-build]');
+    process.exit(2);
+  }
+  const results = await runChecks(key, { build: !args.includes('--no-build') });
+  console.log(formatReport(key, results));
+  process.exit(results.some((result) => result.status === 'FAIL') ? 1 : 0);
+};
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();