create-bestax 4.1.0 → 4.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -10,25 +10,6 @@
     "dist",
     "templates"
   ],
-  "scripts": {
-    "build": "node scripts/sync-skills.mjs && tsc",
-    "prepack": "node scripts/sync-skills.mjs",
-    "dev": "tsc --watch",
-    "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest",
-    "test:watch": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --watch",
-    "test:coverage": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage",
-    "test:e2e": "playwright test --config=e2e/playwright.config.ts",
-    "test:e2e:ui": "playwright test --config=e2e/playwright.config.ts --ui",
-    "test:e2e:headed": "playwright test --config=e2e/playwright.config.ts --headed",
-    "test:e2e:update": "playwright test --config=e2e/playwright.config.ts --update-snapshots",
-    "test:e2e:report": "playwright show-report e2e/playwright-report",
-    "lint": "eslint src e2e/tests e2e/utils",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
-    "clean": "rimraf dist",
-    "release": "npx semantic-release"
-  },
   "keywords": [
     "bestax",
     "bulma",
@@ -73,7 +54,25 @@
     "wait-on": "^9.1.0"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
-  }
-}
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/sync-skills.mjs && tsc",
+    "dev": "tsc --watch",
+    "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest",
+    "test:watch": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --watch",
+    "test:coverage": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage",
+    "test:e2e": "playwright test --config=e2e/playwright.config.ts",
+    "test:e2e:ui": "playwright test --config=e2e/playwright.config.ts --ui",
+    "test:e2e:headed": "playwright test --config=e2e/playwright.config.ts --headed",
+    "test:e2e:update": "playwright test --config=e2e/playwright.config.ts --update-snapshots",
+    "test:e2e:report": "playwright show-report e2e/playwright-report",
+    "lint": "eslint src e2e/tests e2e/utils",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "clean": "rimraf dist",
+    "release": "npx semantic-release"
+  },
+  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/create-bestax)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n\n# Alternative naming\nnpm create bestax-bulma@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (Complete or Minimal)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] [options]\n```\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
+}

package/templates/skills/bestax-custom-component/references/api.md

@@ -12,11 +12,23 @@ Everything below is public API. Where to import from depends on your context:
 Turns Bulma helper props into a class string and returns the leftover (non-helper) props.
 
 ```ts
-const { bulmaHelperClasses, rest } = useBulmaClasses(props);
+const { bulmaHelperClasses, bulmaHelperStyles, rest } = useBulmaClasses(props);
 // bulmaHelperClasses: e.g. 'has-text-primary is-size-3 m-3'
-// rest: every prop that was NOT a recognized helper (safe to spread on the DOM)
+// bulmaHelperStyles: inline styles for scheme-aware values, or undefined (see below)
+// rest: every prop that was NOT a recognized helper; destructure your own
+// component props and `style` before spreading it on a DOM element
 ```
 
+`bulmaHelperStyles` is `undefined` unless `backgroundColor` is one of the six
+`validSchemeColors` values (`scheme-main`, `scheme-main-bis`, `scheme-main-ter`,
+`scheme-invert`, `scheme-invert-bis`, `scheme-invert-ter`). Bulma ships no
+`has-background-scheme-*` classes, so those values emit no class; the hook returns
+`{ backgroundColor: 'var(--bulma-<value>)' }` instead — a dark-mode-safe inline style. Put it
+on the root element with `mergeBulmaStyles(bulmaHelperStyles, style)`
+(`helpers/mergeBulmaStyles.ts`): the user's `style` prop wins on conflicts, and the result is
+`undefined` when both are absent so unaffected components keep an attribute-free DOM.
+(`useColorStyles` is the underlying per-concern hook.)
+
 `BulmaClassesProps` is the union of all helper prop groups, composed from per-concern hooks
 that can also be used on their own:
 
@@ -56,16 +68,22 @@ de-dupes. Related exports:
 Re-exported through `useBulmaClasses`. Use them to type component-specific props and to drive
 Storybook `argTypes`/tests:
 
-`validColors`, `validColorShades`, `validSizes`, `validTextSizes`, `validAlignments`,
-`validTextTransforms`, `validTextWeights`, `validFontFamilies`, `validDisplays`,
-`validVisibilities`, `validFlexDirections`, `validFlexWraps`, `validJustifyContents`,
-`validAlignContents`, `validAlignItems`, `validAlignSelfs`, `validFlexGrowShrink`,
-`validViewports`.
+`validColors`, `validColorShades`, `validSchemeColors`, `validSizes`, `validTextSizes`,
+`validAlignments`, `validTextTransforms`, `validTextWeights`, `validFontFamilies`,
+`validDisplays`, `validVisibilities`, `validFlexDirections`, `validFlexWraps`,
+`validJustifyContents`, `validAlignContents`, `validAlignItems`, `validAlignSelfs`,
+`validFlexGrowShrink`, `validViewports`.
 
 ```ts
 export type MyColor = (typeof validColors)[number];
 ```
 
+`validSchemeColors` is the scheme-background tuple consumed by `bulmaHelperStyles` (above).
+Components that support scheme backgrounds widen their own `bgColor` union with
+`(typeof validSchemeColors)[number]` — the widening is deliberate and per-component, so a
+component that has not wired `bulmaHelperStyles` onto its root element must keep the narrow
+union (a compile error beats a silent no-op).
+
 ## `ConfigProvider` / `Theme` — `helpers/Config.tsx`, `helpers/Theme.tsx`
 
 `ConfigProvider` provides the runtime `classPrefix` (and `iconLibrary`) consumed via `useConfig`;

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -143,7 +143,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 
 - [ConfigProvider](https://bestax.io/docs/api/helpers/config) — The `ConfigProvider` component provides a React context for configuring global settings across all Bulma UI components.
 - [Theme](https://bestax.io/docs/api/helpers/theme) — The `Theme` component provides a powerful way to customize Bulma's appearance using CSS custom properties (CSS variables).
-- [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The `valid*` constant arrays enumerate every accepted value for the shared Bulma helper props — public API you can import to build prop types and validation.
+- [Valid value constants](https://bestax.io/docs/api/helpers/valid-values) — The `valid*` tuples enumerate the core accepted values for the shared Bulma helper props — public API for building prop types and validation.
 - [classNames](https://bestax.io/docs/api/helpers/classnames) — `classNames` is a utility function for conditionally joining class names together.
 - [useBulmaClasses](https://bestax.io/docs/api/helpers/usebulmaclasses) — `useBulmaClasses` is a custom React hook that generates Bulma helper class strings from a set of props.
 - [usePrefixedClassNames](https://bestax.io/docs/api/helpers/useprefixedclassnames) — `usePrefixedClassNames` builds a component class string that honors the `classPrefix` from `ConfigProvider` — the hook every bestax component uses for its own…

package/templates/skills/bestax-layout-scaffold/SKILL.md

@@ -70,10 +70,15 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   `textWeight`, `textSize` directly (their `color` prop colors the cell; for muted cell text
   wrap content in `Span textColor="grey"`). Set the app-wide icon library once with
   `<ConfigProvider iconLibrary="…">` at the root rather than `library` on every `<Icon>`.
-- **Decorative CSS is budgeted: three compact rules, ≤13 lines per app — comments count:
+- **Alternating section bands are a prop, not CSS: `bgColor="scheme-main-bis"` on every
+  other `Section` (next band `scheme-main-ter`).** The scheme values render as a
+  dark-mode-safe inline `background-color: var(--bulma-scheme-*)` — zero custom CSS — and
+  still never `bgColor="light"`/`"white"`: those are fixed colors that stay light when dark
+  mode flips the text.
+- **Decorative CSS is budgeted: two compact rules, ≤10 lines per app — comments count:
   at most one short inline note, never a file-header comment block — every value derived
-  from `--bulma-*`.** A marketing page gets at most one hero wash, one alternating section
-  band, and one featured-card ring, applied via `className` — no resets (Bulma ships one;
+  from `--bulma-*`.** A marketing page gets at most one hero wash and one featured-card
+  ring, applied via `className` — no resets (Bulma ships one;
   body/list margins are already zero) and no grid textures, masks, or multi-layer backdrops;
   the components carry the design:
 
@@ -85,9 +90,6 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
       transparent 60%
     );
   }
-  .section-alt {
-    background: var(--bulma-scheme-main-bis); /* next band: -ter */
-  }
   .featured-ring {
     --bulma-shadow: 0 0 0 2px var(--bulma-primary);
   }
@@ -188,8 +190,10 @@ inline `style`.
 - [ ] Style with helper props, not inline `style` — translate via the mapping table; values
       with no helper get a named class in the stylesheet, never `style={{}}`. No raw Bulma
       `className`s either (`Span`/`Paragraph` wrap bare text; `Th`/`Td` take `textAlign`/`textWeight`).
-- [ ] Decorative CSS ≤13 lines total incl. comments — no file-header comment (hero wash +
-      section band + featured-card ring), `--bulma-*`-derived; no resets — Bulma ships one.
+- [ ] Alternating bands are `bgColor="scheme-main-bis"` (next band `scheme-main-ter`) on
+      every other `Section` — never band CSS, never `bgColor="light"`/`"white"`.
+- [ ] Decorative CSS ≤10 lines total incl. comments — no file-header comment (hero wash +
+      featured-card ring), `--bulma-*`-derived; no resets — Bulma ships one.
       The ring sets `--bulma-shadow` in a CSS rule; `Theme bulmaVars` has no such key.
 - [ ] Set the icon library once via `<ConfigProvider iconLibrary="…">` at the root.
 - [ ] Site built? ~800 KB raw / ~82 KB gzip CSS is the expected default-flavor size — to shrink

package/templates/skills/bestax-layout-scaffold/references/archetypes.md

@@ -155,8 +155,11 @@ the `Hero`; if it's `fixed="top"`, the same `<html class="has-navbar-fixed-top">
 applies here too.
 
 **Alternating section bands:** tint every other `Section` with a scheme step —
-`.section-alt { background: var(--bulma-scheme-main-bis); }` (next step `-ter`) — not
-`bgColor="light"`/`"white"`: those are fixed colors that stay light when dark mode flips the text.
+`bgColor="scheme-main-bis"` (next step `scheme-main-ter`) — not `bgColor="light"`/`"white"`:
+those are fixed colors that stay light when dark mode flips the text. Scheme values emit no
+class; the component renders a dark-mode-safe inline `background-color: var(--bulma-scheme-*)`
+style, so bands cost zero custom CSS. The same values work on `Hero` (and its
+`Head`/`Body`/`Foot`), `Footer`, `Container`, `Box`, and `Card`.
 
 **Hero CTAs:** on a colored hero use **filled** buttons only — `color="light"` for the primary
 CTA and `color="primary" isInverted` (solid white, primary text) for a secondary. A thin

package/templates/skills/bestax-theming/SKILL.md

@@ -44,9 +44,13 @@ color tokens or fixed-color surfaces exist:
   (`--my-canvas: var(--bulma-scheme-main)`) — or flip them yourself under **both** dark-mode
   paths: `[data-theme='dark']` **and** `@media (prefers-color-scheme: dark)` scoped to
   `:root:not([data-theme])`, since `colorMode="system"` removes the attribute (snippets in
-  `references/css-variables.md`). Alternating/tinted section bands are this case:
-  `background: var(--bulma-scheme-main-bis)` (then `-ter`), never `bgColor="light"` —
-  `light`/`white`/grey helper backgrounds are fixed colors that fight dark mode.
+  `references/css-variables.md`). Alternating/tinted section bands are first-class props:
+  `bgColor="scheme-main-bis"` (then `"scheme-main-ter"`) on `Section` (also `Hero`, `Footer`,
+  `Container`, `Box`, `Card`) renders a scheme-tracking inline background — never
+  `bgColor="light"`: `light`/`white`/grey helper backgrounds are fixed colors that fight
+  dark mode. Keep the derive-from-scheme-vars CSS for other custom surfaces. `Theme
+bulmaVars` now accepts `--bulma-scheme-main`/`-bis`/`-ter` (and the `-invert` trio)
+  overrides, so one Theme re-tints every band at once.
 - **Fixed-color surface → fixed-color content.** On a surface that never changes (a dark hero,
   a brand banner), pin the content's colors too: solid/filled buttons and explicit text colors,
   never scheme-derived defaults or thin outlines that depend on the flipping scheme.

package/templates/skills/bestax-theming/references/css-variables.md

@@ -81,13 +81,14 @@ and numeric shades `--bulma-<c>-00` … `--bulma-<c>-95`.
 
 ## Scheme, text, background, border (light/dark surfaces)
 
-| Variable                                                                    | Role                                                  |
-| --------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `--bulma-scheme-h`, `--bulma-scheme-s`                                      | scheme hue/saturation (`Theme`: `schemeH`, `schemeS`) |
-| `--bulma-scheme-main`, `--bulma-scheme-main-bis`, `--bulma-scheme-main-ter` | page/surface backgrounds (main + subtle steps)        |
-| `--bulma-background`                                                        | secondary background                                  |
-| `--bulma-text`, `--bulma-text-strong`, `--bulma-text-weak`                  | body / emphasized / muted text                        |
-| `--bulma-border`, `--bulma-border-weak`                                     | borders                                               |
+| Variable                                                                          | Role                                                                                                                                                       |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bulma-scheme-h`, `--bulma-scheme-s`                                            | scheme hue/saturation (`Theme`: `schemeH`, `schemeS`)                                                                                                      |
+| `--bulma-scheme-main`, `--bulma-scheme-main-bis`, `--bulma-scheme-main-ter`       | page/surface backgrounds (main + subtle steps); `Theme bulmaVars`-overridable, and the scheme `bgColor` values render them inline                          |
+| `--bulma-scheme-invert`, `--bulma-scheme-invert-bis`, `--bulma-scheme-invert-ter` | inverted scheme surfaces; `Theme bulmaVars`-overridable, and the scheme `bgColor` values render them inline (pair with a foreground — see the color guide) |
+| `--bulma-background`                                                              | secondary background                                                                                                                                       |
+| `--bulma-text`, `--bulma-text-strong`, `--bulma-text-weak`                        | body / emphasized / muted text                                                                                                                             |
+| `--bulma-border`, `--bulma-border-weak`                                           | borders                                                                                                                                                    |
 
 ## Radius, typography