create-bascik 1.0.0-rc.6 → 1.0.0-rc.8

package/assets/skills/README.md

@@ -22,16 +22,16 @@ New projects created with `npm create bascik@latest` include these skills alread
 
 ## Skills
 
-| Skill | Use it for |
-|---|---|
-| [`bascik`](bascik/SKILL.md) | Start here: project layout, components, slots, props, the CLI, verifying output, examples, and building a new site |
-| [`bascik-components`](bascik-components/SKILL.md) | Component CSS and scripts that work with many instances, interactivity, and theming |
-| [`bascik-compatibility`](bascik-compatibility/SKILL.md) | Which HTML, CSS, and JavaScript features to use: Baseline support and Bascik scoping |
-| [`bascik-scripts`](bascik-scripts/SKILL.md) | Build, routes, server, and stream scripts, API routes, and Markdown blogs |
-| [`bascik-seo`](bascik-seo/SKILL.md) | Head tags, social cards, structured data, sitemap, and `llms.txt` |
-| [`bascik-config`](bascik-config/SKILL.md) | `bascik.config.ts`, exec scripts, assets, deployment, and monorepos |
-| [`bascik-testing`](bascik-testing/SKILL.md) | Unit and E2E tests, debugging, spec validation, Lighthouse |
-| [`bascik-migrate`](bascik-migrate/SKILL.md) | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress |
+| Skill                                                   | Use it for                                                                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`bascik`](bascik/SKILL.md)                             | Start here: project layout, components, slots, props, the CLI, verifying output, examples, and building a new site |
+| [`bascik-components`](bascik-components/SKILL.md)       | Component CSS and scripts that work with many instances, interactivity, and theming                                |
+| [`bascik-compatibility`](bascik-compatibility/SKILL.md) | Which HTML, CSS, and JavaScript features to use: Baseline support and Bascik scoping                               |
+| [`bascik-scripts`](bascik-scripts/SKILL.md)             | Build, routes, server, and stream scripts, API routes, and Markdown blogs                                          |
+| [`bascik-seo`](bascik-seo/SKILL.md)                     | Head tags, social cards, structured data, sitemap, and `llms.txt`                                                  |
+| [`bascik-config`](bascik-config/SKILL.md)               | `bascik.config.ts`, exec scripts, assets, deployment, and monorepos                                                |
+| [`bascik-testing`](bascik-testing/SKILL.md)             | Unit and E2E tests, debugging, spec validation, Lighthouse                                                         |
+| [`bascik-migrate`](bascik-migrate/SKILL.md)             | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress                                |
 
 The skills hold the rules an assistant must follow and point to the docs at https://bascik.dev for everything else, so the guidance lives in one place. `bascik/scripts/read-doc.mjs` prints any docs page.
 
@@ -39,23 +39,23 @@ The skills hold the rules an assistant must follow and point to the docs at http
 
 The skills ship dependency-free Node.js scripts (Node 22.18+) that agents run from the project root:
 
-| Script | Purpose |
-|---|---|
-| `bascik/scripts/verify.mjs` | `bascik --check` plus the language server linter (including component folders outside the project), optionally a build |
-| `bascik/scripts/preview.mjs` | Compile a snippet or page with the project's components and print readable output |
-| `bascik/scripts/list-components.mjs` | Inventory components with props, slots, and descriptions |
-| `bascik/scripts/new-component.mjs` | Create a component that follows the conventions |
-| `bascik/scripts/search-docs.mjs` | Search the live docs |
-| `bascik/scripts/read-doc.mjs` | Print a docs page as text |
-| `bascik/scripts/add-example.mjs` | Copy an example from https://bascik.dev/example-components into the project |
-| `bascik/scripts/check-links.mjs` | Find broken internal links and `#fragments` in `dist/` |
-| `bascik-components/scripts/check-tokens.mjs` | Find CSS custom properties components use but nothing declares |
-| `bascik-compatibility/scripts/lookup.mjs` | Search Bascik's live compatibility matrix |
-| `bascik-compatibility/scripts/baseline.mjs` | Baseline browser support for a web feature |
-| `bascik-scripts/scripts/new-post.mjs` | Create a Markdown post with valid front matter |
-| `bascik-seo/scripts/audit-seo.mjs` | Check titles, descriptions, canonicals, social tags, and JSON-LD in `dist/` |
-| `bascik-config/scripts/audit-config.mjs` | Flag redundant or risky `bascik.config.ts` values |
-| `bascik-config/scripts/check-workspace.mjs` | Map every site in a repository and report cross-site problems |
+| Script                                       | Purpose                                                                                                                |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `bascik/scripts/verify.mjs`                  | `bascik --check` plus the language server linter (including component folders outside the project), optionally a build |
+| `bascik/scripts/preview.mjs`                 | Compile a snippet or page with the project's components and print readable output                                      |
+| `bascik/scripts/list-components.mjs`         | Inventory components with props, slots, and descriptions                                                               |
+| `bascik/scripts/new-component.mjs`           | Create a component that follows the conventions                                                                        |
+| `bascik/scripts/search-docs.mjs`             | Search the live docs                                                                                                   |
+| `bascik/scripts/read-doc.mjs`                | Print a docs page as text                                                                                              |
+| `bascik/scripts/add-example.mjs`             | Copy an example from https://bascik.dev/example-components into the project                                            |
+| `bascik/scripts/check-links.mjs`             | Find broken internal links and `#fragments` in `dist/`                                                                 |
+| `bascik-components/scripts/check-tokens.mjs` | Find CSS custom properties components use but nothing declares                                                         |
+| `bascik-compatibility/scripts/lookup.mjs`    | Search Bascik's live compatibility matrix                                                                              |
+| `bascik-compatibility/scripts/baseline.mjs`  | Baseline browser support for a web feature                                                                             |
+| `bascik-scripts/scripts/new-post.mjs`        | Create a Markdown post with valid front matter                                                                         |
+| `bascik-seo/scripts/audit-seo.mjs`           | Check titles, descriptions, canonicals, social tags, and JSON-LD in `dist/`                                            |
+| `bascik-config/scripts/audit-config.mjs`     | Flag redundant or risky `bascik.config.ts` values                                                                      |
+| `bascik-config/scripts/check-workspace.mjs`  | Map every site in a repository and report cross-site problems                                                          |
 
 The example components and the starter site live in the repository's [`examples/`](https://github.com/bascikdev/bascik/tree/main/examples) folder, not in the skills. The docs build publishes them at `https://bascik.dev/assets/examples.json`, which `add-example.mjs` downloads.
 

package/assets/skills/bascik/SKILL.md

@@ -19,7 +19,7 @@ Code in this skill is illustrative. Adapt tag names, paths, and values to the pr
 
 - `package.json` depends on `@bascik/bascik`, or the root has `bascik.config.ts` / `bascik.config.js`, or there are `.html` files under `src/components/`.
 - Node.js 22.18 or newer (24 LTS recommended). Node runs `.ts` helpers natively, so no TypeScript build step exists.
-- Standard scripts: `npm run dev` (`bascik`), `npm run build` (`bascik --build`), `npm run lint` (`bascik-language-server --check`).
+- Standard scripts: `npm run dev` (`bascik`), `npm run build` (`bascik --build`), `npm run lint` (`bascik --check`).
 
 ## Project layout
 
@@ -48,15 +48,20 @@ Default pattern: `<style>` above the markup, markup in the middle, `<script>` be
 ```html
 <!-- src/components/like-button/like-button.html -->
 <style>
-  .like { padding: 0.5rem 1rem; border-radius: 6px; }
-  .like.active { background: #d3ff8d; }
+  .like {
+    padding: 0.5rem 1rem;
+    border-radius: 6px;
+  }
+  .like.active {
+    background: #d3ff8d;
+  }
 </style>
 <button class="like" id="btn" type="button">
   <span data-bascik-prop-label>Like</span>
 </button>
 <script>
-  const btn = document.getElementById('btn');
-  btn.addEventListener('click', () => btn.classList.toggle('active'));
+  const btn = document.getElementById("btn");
+  btn.addEventListener("click", () => btn.classList.toggle("active"));
 </script>
 ```
 
@@ -87,26 +92,26 @@ New components are picked up by the running dev server automatically; no restart
 
 ## Slots, props, and attributes
 
-| Need | Component template | Usage site |
-|---|---|---|
-| Default slot (rich HTML) | `<div data-bascik-slot>fallback</div>` | `<my-card><h2>Title</h2></my-card>` |
-| Named slot | `<div data-bascik-slot="header"></div>` | `<div data-bascik-slot="header"><h1>Hi</h1></div>` inside the tag |
-| Text prop | `<p data-bascik-prop-title></p>` | `<my-card data-bascik-prop-title="Hello" />` |
-| Prop into an attribute | `<img data-bascik-attr-src="image" data-bascik-attr-alt="alt">` | `<my-card data-bascik-prop-image="/a.png" data-bascik-prop-alt="A" />` |
-| Forward attributes | (nothing) | `<my-card class="wide" aria-label="Promo" />` lands on the first root element |
+| Need                     | Component template                                              | Usage site                                                                    |
+| ------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Default slot (rich HTML) | `<div data-bascik-slot>fallback</div>`                          | `<my-card><h2>Title</h2></my-card>`                                           |
+| Named slot               | `<div data-bascik-slot="header"></div>`                         | `<div data-bascik-slot="header"><h1>Hi</h1></div>` inside the tag             |
+| Text prop                | `<p data-bascik-prop-title></p>`                                | `<my-card data-bascik-prop-title="Hello" />`                                  |
+| Prop into an attribute   | `<img data-bascik-attr-src="image" data-bascik-attr-alt="alt">` | `<my-card data-bascik-prop-image="/a.png" data-bascik-prop-alt="A" />`        |
+| Forward attributes       | (nothing)                                                       | `<my-card class="wide" aria-label="Promo" />` lands on the first root element |
 
 Pass props as `data-bascik-prop-<name>="..."` on the usage tag. A plain attribute such as `label="..."` is not a prop: it is forwarded to the root element and the prop keeps its default. The slot element itself is replaced by the content, so named-slot wrappers disappear: wrap headings and links in a `<div data-bascik-slot="x">` rather than putting the attribute on the `<h1>` or `<a>`. Details: `read-doc.mjs /slots`, `/props`, `/attribute-inheritance`.
 
 ## Script tags at a glance
 
-| Tag | Runs | Use for |
-|---|---|---|
-| `<script>` | Browser | Component and page behavior (scoped, IIFE-wrapped) |
-| `<script data-bascik-build>` | Node, at build time | Markup from files, Markdown, APIs; output replaces the tag |
-| `<script data-bascik-routes>` | Node, at build time | Expanding `[slug].html` templates into many pages |
-| `<script data-bascik-server>` | Node, per request | Personalized markup (needs `bascik --server` or a serverless target) |
-| `<script data-bascik-stream>` | Node, per request, streamed | Slow per-request blocks that should not delay the page shell |
-| `<script data-bascik-dev>` | Browser, dev only | Debug helpers removed from production builds |
+| Tag                           | Runs                        | Use for                                                              |
+| ----------------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `<script>`                    | Browser                     | Component and page behavior (scoped, IIFE-wrapped)                   |
+| `<script data-bascik-build>`  | Node, at build time         | Markup from files, Markdown, APIs; output replaces the tag           |
+| `<script data-bascik-routes>` | Node, at build time         | Expanding `[slug].html` templates into many pages                    |
+| `<script data-bascik-server>` | Node, per request           | Personalized markup (needs `bascik --server` or a serverless target) |
+| `<script data-bascik-stream>` | Node, per request, streamed | Slow per-request blocks that should not delay the page shell         |
+| `<script data-bascik-dev>`    | Browser, dev only           | Debug helpers removed from production builds                         |
 
 Node-side scripts export a default function that returns an HTML string. Details are in the `bascik-scripts` skill.
 
@@ -117,19 +122,22 @@ bascik                      # dev server at http://localhost:8080 with live relo
 bascik --build              # production build to dist/ (HTML, CSS, JS, and identifier minification on)
 bascik --build --only "blog/**"   # rebuild matching pages without cleaning dist/
 bascik --server             # serve a built dist/ (needed for server/stream scripts and API routes)
-bascik --check              # validate pages, components, config, and API routes without building
+bascik --check              # project checks, plus the per-file checks when @bascik/language-server is installed
+bascik --check --fix        # also rewrite fixable findings (needs @bascik/language-server)
 bascik add <package>        # copy components from an installed npm package into src/components/
 bascik init                 # add Bascik to an existing project
-npx @bascik/language-server --check   # lint scoping patterns, unclosed tags, and directives
+npx @bascik/language-server --check   # the per-file checks on their own (bascik --check already runs them)
 ```
 
+`bascik --check` and the linter are not two overlapping tools. `bascik --check` answers project questions (duplicate routes, unused components, config), and the linter answers per-file questions (attribute typos, CSS that cannot be scoped). `bascik --check` runs the linter too, so use it, and reach for the linter alone only on a folder outside the project.
+
 New project: `npm create bascik@latest my-site -y`. Production builds need a site URL for `sitemap.xml` and `robots.txt`: `BASCIK_SITE_URL=https://example.com bascik --build` (or `--site-url`, or `.env`). Full CLI and error output: `read-doc.mjs /cli`.
 
 ## Verify every change
 
 Do not stop at "the file looks right". Run these from the project root:
 
-1. `node <skill-dir>/scripts/verify.mjs` runs `bascik --check` and the language server linter and summarizes both. Add `--build` to also run a production build.
+1. `node <skill-dir>/scripts/verify.mjs` runs `bascik --check` (project and per-file checks) and, for component folders outside the project, the linter, then summarizes each step. Add `--build` to also run a production build.
 2. `node <skill-dir>/scripts/preview.mjs '<my-card data-bascik-prop-title="Hi" />' --count 2` compiles a snippet with the project's real components and config and prints the unminified output, so you can confirm scoped names, slot placement, and script rewrites.
 3. Read the relevant file in `dist/` after a build. A hyphenated tag still present in `dist/` means no component matched it.
 
@@ -139,16 +147,16 @@ Do not stop at "the file looks right". Run these from the project root:
 
 All scripts are dependency-free Node.js (22.18+) and run from the project root. Each prints `--help`.
 
-| Script | Purpose |
-|---|---|
-| [`scripts/verify.mjs`](scripts/verify.mjs) | `bascik --check` plus `@bascik/language-server --check`, with an optional `--build` |
-| [`scripts/preview.mjs`](scripts/preview.mjs) | Compile a snippet, file, or existing page in a temporary build and print the result |
-| [`scripts/list-components.mjs`](scripts/list-components.mjs) | Inventory components with their props, slots, companion files, and `@bascik` descriptions |
-| [`scripts/new-component.mjs`](scripts/new-component.mjs) | Create a component folder that follows the naming and ordering rules |
-| [`scripts/search-docs.mjs`](scripts/search-docs.mjs) | Search the live docs at bascik.dev for a topic |
-| [`scripts/read-doc.mjs`](scripts/read-doc.mjs) | Print the current text of a docs page, such as `/scoped-javascript` |
-| [`scripts/add-example.mjs`](scripts/add-example.mjs) | Copy a tested example component or part of the starter site from bascik.dev into the project (`--list` shows them) |
-| [`scripts/check-links.mjs`](scripts/check-links.mjs) | Find broken internal links, missing assets, and dead `#fragments` in the built `dist/`, honoring `base` |
+| Script                                                       | Purpose                                                                                                            |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`scripts/verify.mjs`](scripts/verify.mjs)                   | `bascik --check`, plus the linter on component folders outside the project, with an optional `--build`             |
+| [`scripts/preview.mjs`](scripts/preview.mjs)                 | Compile a snippet, file, or existing page in a temporary build and print the result                                |
+| [`scripts/list-components.mjs`](scripts/list-components.mjs) | Inventory components with their props, slots, companion files, and `@bascik` descriptions                          |
+| [`scripts/new-component.mjs`](scripts/new-component.mjs)     | Create a component folder that follows the naming and ordering rules                                               |
+| [`scripts/search-docs.mjs`](scripts/search-docs.mjs)         | Search the live docs at bascik.dev for a topic                                                                     |
+| [`scripts/read-doc.mjs`](scripts/read-doc.mjs)               | Print the current text of a docs page, such as `/scoped-javascript`                                                |
+| [`scripts/add-example.mjs`](scripts/add-example.mjs)         | Copy a tested example component or part of the starter site from bascik.dev into the project (`--list` shows them) |
+| [`scripts/check-links.mjs`](scripts/check-links.mjs)         | Find broken internal links, missing assets, and dead `#fragments` in the built `dist/`, honoring `base`            |
 
 Run `list-components.mjs` before creating a component so you reuse what exists instead of duplicating it.
 
@@ -161,15 +169,15 @@ node <skill-dir>/scripts/read-doc.mjs /dynamic-routes
 node <skill-dir>/scripts/search-docs.mjs "dynamic routes trailing slash"
 ```
 
-| How do I... | Read |
-|---|---|
-| Write components, slots, props, attributes | `/components`, `/slots`, `/props`, `/attribute-inheritance` |
-| Pass shared `<head>` tags | `/how-to/templating` |
-| Use a library (petite-vue, Alpine.js, HTMX, Tailwind) | `/libraries` |
-| Use a third-party web component | `/how-to/third-party-web-components` |
-| Share components between projects | `/how-to/sharing-components`, `/how-to/publishing-components` |
-| Find answers to edge cases | `/faq` |
-| Use the CLI and the dev server | `/cli`, `/development-server` |
+| How do I...                                           | Read                                                          |
+| ----------------------------------------------------- | ------------------------------------------------------------- |
+| Write components, slots, props, attributes            | `/components`, `/slots`, `/props`, `/attribute-inheritance`   |
+| Pass shared `<head>` tags                             | `/how-to/templating`                                          |
+| Use a library (petite-vue, Alpine.js, HTMX, Tailwind) | `/libraries`                                                  |
+| Use a third-party web component                       | `/how-to/third-party-web-components`                          |
+| Share components between projects                     | `/how-to/sharing-components`, `/how-to/publishing-components` |
+| Find answers to edge cases                            | `/faq`                                                        |
+| Use the CLI and the dev server                        | `/cli`, `/development-server`                                 |
 
 The full page index is at https://bascik.dev/llms.txt.
 
@@ -195,15 +203,15 @@ The script downloads from bascik.dev, maps files to the project's configured fol
 
 ## Companion skills
 
-| Skill | Load it when |
-|---|---|
-| `bascik-components` | Writing component CSS or `<script>` code, adding interactivity, theming, or compiled class and ID names look wrong |
-| `bascik-compatibility` | Deciding whether an HTML, CSS, or JavaScript feature works in browsers and inside a component |
-| `bascik-scripts` | Using `data-bascik-build`, `-routes`, `-server`, `-stream`, API routes, Markdown, or a blog |
-| `bascik-seo` | Titles, descriptions, canonical URLs, social cards, JSON-LD, sitemap, `llms.txt` |
-| `bascik-config` | Creating or editing `bascik.config.ts`, monorepos, deploying, or running `bascik --server` |
-| `bascik-testing` | Writing tests, debugging, validating output, or tuning Lighthouse scores |
-| `bascik-migrate` | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress |
+| Skill                  | Load it when                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `bascik-components`    | Writing component CSS or `<script>` code, adding interactivity, theming, or compiled class and ID names look wrong |
+| `bascik-compatibility` | Deciding whether an HTML, CSS, or JavaScript feature works in browsers and inside a component                      |
+| `bascik-scripts`       | Using `data-bascik-build`, `-routes`, `-server`, `-stream`, API routes, Markdown, or a blog                        |
+| `bascik-seo`           | Titles, descriptions, canonical URLs, social cards, JSON-LD, sitemap, `llms.txt`                                   |
+| `bascik-config`        | Creating or editing `bascik.config.ts`, monorepos, deploying, or running `bascik --server`                         |
+| `bascik-testing`       | Writing tests, debugging, validating output, or tuning Lighthouse scores                                           |
+| `bascik-migrate`       | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress                                |
 
 If the companions or this skill's `scripts/` folder are missing, the skill was installed as a single file. Reinstall the full set:
 

package/assets/skills/bascik/scripts/add-example.mjs

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
 // Copy an example component or site from https://bascik.dev/example-components into the current Bascik project.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { parseArgs } from 'node:util';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { componentRoots, docsBaseUrl, fail, findProjectRoot, isMain, loadProjectConfig, pagesDirectory } from './lib/project.mjs';
-import { listComponents } from './lib/components.mjs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  componentRoots,
+  docsBaseUrl,
+  fail,
+  findProjectRoot,
+  isMain,
+  loadProjectConfig,
+  pagesDirectory,
+} from "./lib/project.mjs";
+import { listComponents } from "./lib/components.mjs";
 
 const HELP = `Usage: node add-example.mjs --list
        node add-example.mjs <example>[/<path>] [...more] [--dry-run] [--force]
@@ -36,26 +44,38 @@ Options:
 Environment:
   BASCIK_DOCS_URL   Docs origin (default https://bascik.dev)`;
 
-const REFERENCE_ONLY = new Set(['bascik.config.ts', 'bascik.config.js', 'package.json', 'README.md']);
+const REFERENCE_ONLY = new Set([
+  "bascik.config.ts",
+  "bascik.config.js",
+  "package.json",
+  "README.md",
+]);
 
 /** Load the examples bundle from a URL or a local file. Exported for tests. */
-export async function loadBundle(source = `${docsBaseUrl()}/assets/examples.json`) {
+export async function loadBundle(
+  source = `${docsBaseUrl()}/assets/examples.json`,
+) {
   let text;
   if (/^https?:\/\//i.test(source)) {
     let response;
     try {
       response = await fetch(source, { signal: AbortSignal.timeout(20_000) });
     } catch (error) {
-      throw new Error(`could not reach ${source}: ${error.message}. Check the network, or pass --source <examples.json>.`);
+      throw new Error(
+        `could not reach ${source}: ${error.message}. Check the network, or pass --source <examples.json>.`,
+      );
     }
-    if (!response.ok) throw new Error(`${source} returned HTTP ${response.status}`);
+    if (!response.ok)
+      throw new Error(`${source} returned HTTP ${response.status}`);
     text = await response.text();
   } else {
-    text = readFileSync(resolve(source), 'utf8');
+    text = readFileSync(resolve(source), "utf8");
   }
   const bundle = JSON.parse(text);
   if (bundle?.version !== 1 || !Array.isArray(bundle.examples)) {
-    throw new Error(`${source} is not a supported examples bundle (version ${bundle?.version}). Update the skills.`);
+    throw new Error(
+      `${source} is not a supported examples bundle (version ${bundle?.version}). Update the skills.`,
+    );
   }
   return bundle;
 }
@@ -66,22 +86,32 @@ export async function loadBundle(source = `${docsBaseUrl()}/assets/examples.json
  */
 export function destinationFor(example, filePath, layout) {
   const segments = filePath.split(/[\\/]/);
-  if (isAbsolute(filePath) || segments.some((segment) => segment === '..' || segment === '' || segment === '.')) {
+  if (
+    isAbsolute(filePath) ||
+    segments.some(
+      (segment) => segment === ".." || segment === "" || segment === ".",
+    )
+  ) {
     throw new Error(`unsafe path in the examples bundle: ${filePath}`);
   }
-  if (example.kind === 'component') {
-    if (typeof example.name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(example.name)) {
-      throw new Error(`unsafe example name in the examples bundle: ${example.name}`);
+  if (example.kind === "component") {
+    if (
+      typeof example.name !== "string" ||
+      !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(example.name)
+    ) {
+      throw new Error(
+        `unsafe example name in the examples bundle: ${example.name}`,
+      );
     }
     return join(layout.componentRoot, example.name, filePath);
   }
   if (REFERENCE_ONLY.has(filePath)) return undefined;
-  const [first, second, ...rest] = filePath.split('/');
-  if (first === 'src') {
-    const tail = rest.join('/');
-    if (second === 'components') return join(layout.componentRoot, tail);
-    if (second === 'pages') return join(layout.pagesDir, tail);
-    if (second === 'api') return join(layout.apiDir, tail);
+  const [first, second, ...rest] = filePath.split("/");
+  if (first === "src") {
+    const tail = rest.join("/");
+    if (second === "components") return join(layout.componentRoot, tail);
+    if (second === "pages") return join(layout.pagesDir, tail);
+    if (second === "api") return join(layout.apiDir, tail);
     return join(layout.importRoot, second, tail);
   }
   return join(layout.root, filePath);
@@ -92,21 +122,34 @@ export function destinationFor(example, filePath, layout) {
  * [{ example, file }] with each file once. Throws on an unknown reference. Exported for tests.
  */
 export function selectFiles(bundle, references) {
-  const byName = new Map(bundle.examples.map((example) => [example.name, example]));
+  const byName = new Map(
+    bundle.examples.map((example) => [example.name, example]),
+  );
   const picked = new Map();
-  const add = (example, file) => picked.set(`${example.name}/${file.path}`, { example, file });
+  const add = (example, file) =>
+    picked.set(`${example.name}/${file.path}`, { example, file });
   // [example the using file belongs to, component name]
   const queue = [];
   for (const reference of references) {
-    const [name, ...rest] = reference.replace(/\\/g, '/').replace(/\/+$/, '').split('/');
+    const [name, ...rest] = reference
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "")
+      .split("/");
     const example = byName.get(name);
     if (!example) {
-      const names = bundle.examples.map((e) => e.name).join(', ');
+      const names = bundle.examples.map((e) => e.name).join(", ");
       throw new Error(`no example named "${name}". Available: ${names}`);
     }
-    const path = rest.join('/');
-    const files = path ? example.files.filter((file) => file.path === path || file.path.startsWith(`${path}/`)) : example.files;
-    if (files.length === 0) throw new Error(`${name} has no file or folder "${path}". Run with --list, or see ${example.docs}`);
+    const path = rest.join("/");
+    const files = path
+      ? example.files.filter(
+          (file) => file.path === path || file.path.startsWith(`${path}/`),
+        )
+      : example.files;
+    if (files.length === 0)
+      throw new Error(
+        `${name} has no file or folder "${path}". Run with --list, or see ${example.docs}`,
+      );
     for (const file of files) {
       add(example, file);
       queue.push(...file.uses.map((name) => [example, name]));
@@ -116,8 +159,15 @@ export function selectFiles(bundle, references) {
   while (queue.length) {
     const [owner, name] = queue.shift();
     // A site's own src/components/<name>/ wins over the example component of the same name.
-    const local = owner.kind === 'site' ? owner.files.filter((file) => new RegExp(`^src/components/(?:.*/)?${name}/`).test(file.path)) : [];
-    const [example, files] = local.length ? [owner, local] : [byName.get(name), byName.get(name)?.files ?? []];
+    const local =
+      owner.kind === "site"
+        ? owner.files.filter((file) =>
+            new RegExp(`^src/components/(?:.*/)?${name}/`).test(file.path),
+          )
+        : [];
+    const [example, files] = local.length
+      ? [owner, local]
+      : [byName.get(name), byName.get(name)?.files ?? []];
     const key = `${example?.name}:${name}`;
     if (!example || seen.has(key)) continue;
     seen.add(key);
@@ -133,14 +183,15 @@ async function main() {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
-      list: { type: 'boolean', default: false },
-      'dry-run': { type: 'boolean', default: false },
-      force: { type: 'boolean', default: false },
-      source: { type: 'string' },
-      help: { type: 'boolean', short: 'h', default: false },
+      list: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      source: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
     },
   });
-  if (values.help || (!values.list && positionals.length === 0)) return console.log(HELP);
+  if (values.help || (!values.list && positionals.length === 0))
+    return console.log(HELP);
 
   let bundle;
   try {
@@ -152,14 +203,18 @@ async function main() {
   const docsLink = (example) => new URL(example.docs, `${docsBaseUrl()}/`).href;
 
   if (values.list) {
-    for (const kind of ['component', 'site']) {
-      const examples = bundle.examples.filter((example) => example.kind === kind);
+    for (const kind of ["component", "site"]) {
+      const examples = bundle.examples.filter(
+        (example) => example.kind === kind,
+      );
       if (!examples.length) continue;
-      console.log(`\n${kind === 'component' ? 'Components' : 'Sites'}`);
+      console.log(`\n${kind === "component" ? "Components" : "Sites"}`);
       for (const example of examples) {
-        const firstSentence = example.description.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? example.description;
+        const firstSentence =
+          example.description.match(/^.*?[.!?](?=\s|$)/)?.[0] ??
+          example.description;
         console.log(`  ${example.name.padEnd(16)} ${firstSentence}`);
-        console.log(`  ${''.padEnd(16)} ${docsLink(example)}`);
+        console.log(`  ${"".padEnd(16)} ${docsLink(example)}`);
       }
     }
     return;
@@ -167,15 +222,19 @@ async function main() {
 
   const root = findProjectRoot();
   const config = await loadProjectConfig(root);
-  if (config?.error) fail(`add-example: could not load ${config.path}: ${config.error.message}`);
+  if (config?.error)
+    fail(`add-example: could not load ${config.path}: ${config.error.message}`);
   const directory = config?.module?.default?.directory ?? {};
   const roots = componentRoots(root, config?.module);
   const layout = {
     root,
     componentRoot: roots[0],
     pagesDir: pagesDirectory(root, config?.module),
-    importRoot: resolve(root, config?.module?.default?.scripts?.importRoot ?? 'src'),
-    apiDir: resolve(root, directory.api ?? 'src/api'),
+    importRoot: resolve(
+      root,
+      config?.module?.default?.scripts?.importRoot ?? "src",
+    ),
+    apiDir: resolve(root, directory.api ?? "src/api"),
   };
 
   let selected;
@@ -196,55 +255,93 @@ async function main() {
       fail(`add-example: ${error.message}`);
     }
     if (!destination) {
-      if (file.path !== 'README.md') printed.push({ example, file });
+      if (file.path !== "README.md") printed.push({ example, file });
       continue;
     }
-    if (destination.endsWith('.html') && example.kind === 'component' && file.path === `${example.name}.html`) {
-      const clash = existingComponents.find((c) => c.tag === example.name && resolve(root, c.file) !== destination);
+    if (
+      destination.endsWith(".html") &&
+      example.kind === "component" &&
+      file.path === `${example.name}.html`
+    ) {
+      const clash = existingComponents.find(
+        (c) => c.tag === example.name && resolve(root, c.file) !== destination,
+      );
       if (clash) {
-        const same = readFileSync(resolve(root, clash.file), 'utf8') === file.content;
+        const same =
+          readFileSync(resolve(root, clash.file), "utf8") === file.content;
         if (same) {
           console.log(`same  ${clash.file}  (already in the project)`);
           continue;
         }
-        fail(`add-example: a component named <${example.name}> already exists at ${clash.file}. Rename one of them first.`);
+        fail(
+          `add-example: a component named <${example.name}> already exists at ${clash.file}. Rename one of them first.`,
+        );
       }
     }
     plan.push({ example, file, destination });
   }
 
-  const show = (path) => relative(root, path).replace(/\\/g, '/');
-  const conflicts = plan.filter(({ file, destination }) => existsSync(destination) && readFileSync(destination, 'utf8') !== file.content);
+  const show = (path) => relative(root, path).replace(/\\/g, "/");
+  const conflicts = plan.filter(
+    ({ file, destination }) =>
+      existsSync(destination) &&
+      readFileSync(destination, "utf8") !== file.content,
+  );
   if (conflicts.length && !values.force) {
-    const list = conflicts.map(({ example, file, destination }) => `  ${show(destination)}  (compare with ${docsLink(example)}, file ${file.path})`);
-    fail(`add-example: these files already exist and differ; nothing was written. Merge by hand, or rerun with --force:\n${list.join('\n')}`);
+    const list = conflicts.map(
+      ({ example, file, destination }) =>
+        `  ${show(destination)}  (compare with ${docsLink(example)}, file ${file.path})`,
+    );
+    fail(
+      `add-example: these files already exist and differ; nothing was written. Merge by hand, or rerun with --force:\n${list.join("\n")}`,
+    );
   }
 
   let written = 0;
   for (const { file, destination } of plan) {
-    if (existsSync(destination) && readFileSync(destination, 'utf8') === file.content) {
+    if (
+      existsSync(destination) &&
+      readFileSync(destination, "utf8") === file.content
+    ) {
       console.log(`same  ${show(destination)}`);
       continue;
     }
-    console.log(`${values['dry-run'] ? 'would' : 'write'} ${show(destination)}`);
-    if (values['dry-run']) continue;
+    console.log(
+      `${values["dry-run"] ? "would" : "write"} ${show(destination)}`,
+    );
+    if (values["dry-run"]) continue;
     mkdirSync(dirname(destination), { recursive: true });
     writeFileSync(destination, file.content);
     written++;
   }
 
   for (const { example, file } of printed) {
-    console.log(`\n--- ${example.name}/${file.path} (not copied: merge what you need by hand) ---\n${file.content.trimEnd()}`);
+    console.log(
+      `\n--- ${example.name}/${file.path} (not copied: merge what you need by hand) ---\n${file.content.trimEnd()}`,
+    );
   }
-  const packageJson = printed.find(({ file }) => file.path === 'package.json');
+  const packageJson = printed.find(({ file }) => file.path === "package.json");
   if (packageJson) {
-    const wanted = Object.keys(JSON.parse(packageJson.file.content).dependencies ?? {});
-    const projectPackage = existsSync(join(root, 'package.json')) ? JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) : {};
-    const have = new Set([...Object.keys(projectPackage.dependencies ?? {}), ...Object.keys(projectPackage.devDependencies ?? {})]);
+    const wanted = Object.keys(
+      JSON.parse(packageJson.file.content).dependencies ?? {},
+    );
+    const projectPackage = existsSync(join(root, "package.json"))
+      ? JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+      : {};
+    const have = new Set([
+      ...Object.keys(projectPackage.dependencies ?? {}),
+      ...Object.keys(projectPackage.devDependencies ?? {}),
+    ]);
     const missing = wanted.filter((name) => !have.has(name));
-    if (missing.length) console.log(`\nInstall the dependencies this example uses: npm install ${missing.join(' ')}`);
+    if (missing.length)
+      console.log(
+        `\nInstall the dependencies this example uses: npm install ${missing.join(" ")}`,
+      );
   }
-  if (!values['dry-run']) console.log(`\n${written} file${written === 1 ? '' : 's'} written. Read each file's comments for setup steps.`);
+  if (!values["dry-run"])
+    console.log(
+      `\n${written} file${written === 1 ? "" : "s"} written. Read each file's comments for setup steps.`,
+    );
 }
 
 if (isMain(import.meta.url)) await main();