@keenmate/web-components-devkit 1.0.0-rc05 → 1.0.0-rc07

package/src/cli/commands/check-vars.js

@@ -8,10 +8,12 @@
  *
  * Contract (prefix = kmwc.prefix or manifest.prefix, e.g. `ms`):
  *   - every `--base-*` read via var() must be in baseVariables, and vice versa
- *   - checkMode "declared" (default): every `--<prefix>-*` DECLARED (`--x:`)
- *     must be in componentVariables, and vice versa
- *   - checkMode "consumed": the same, but against `var(--<prefix>-*)` reads (for
- *     components whose public knobs are read-with-fallback, never declared)
+ *   - checkMode "declared" (default): every `--<prefix>-*` DECLARED (`--x:`) or
+ *     READ (`var(--x)`) must be in componentVariables, and vice versa. A read
+ *     without a declaration is an input variable — a public knob that is unset by
+ *     design, e.g. one forwarded to core's menu so a page-wide value still applies
+ *   - checkMode "consumed": only `var(--<prefix>-*)` reads count (for components
+ *     whose knobs are all read-with-fallback; a declared-but-unread name is dead)
  *   - names in kmwc.cssVariables.internalVariables are runtime internals — exempt
  *
  * Undocumented component variables are a warning unless --strict; everything else errors.
@@ -25,7 +27,9 @@ const STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.pcss
 /**
  * Directories are scanned for stylesheets; a file listed explicitly is read
  * whatever its type — e.g. a built bundle that inlines the compiled CSS, for
- * components whose SCSS generates variable names via interpolation.
+ * components whose SCSS generates variable names via interpolation, or a core
+ * module whose CSS the component renders (`@keenmate/web-components-core/dist/menu/styles.js`
+ * — a package path resolves from node_modules).
  */
 function getStylesheetTexts(sourcePath, stylesheetTexts, isExplicit = true) {
   if (!existsSync(sourcePath)) throw new Error(`cssVariables source not found: ${sourcePath}`);
@@ -37,6 +41,14 @@ function getStylesheetTexts(sourcePath, stylesheetTexts, isExplicit = true) {
   return stylesheetTexts;
 }
 
+/** A source relative to the repo, else a package path (`@scope/pkg/dist/x.js`) under node_modules. */
+function resolveSourcePath(root, sourcePath) {
+  const repoPath = resolve(root, sourcePath);
+  if (existsSync(repoPath) || sourcePath.startsWith('.')) return repoPath;
+  const packagePath = resolve(root, 'node_modules', sourcePath);
+  return existsSync(packagePath) ? packagePath : repoPath;
+}
+
 const mapToRegExpSource = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /** Pure verdict — exported for tests. */
@@ -48,7 +60,7 @@ export function checkManifestVariables({ cssText, manifest, prefix, internalVari
   const consumedVariables = new Set([...cssText.matchAll(new RegExp(`var\\(\\s*--(${prefixSource}-[a-z0-9-]+)`, 'gi'))].map((match) => match[1]));
   const consumedBaseVariables = new Set([...cssText.matchAll(/var\(\s*--(base-[a-z0-9-]+)/gi)].map((match) => match[1]));
 
-  const componentVariablesInCss = checkMode === 'consumed' ? consumedVariables : declaredVariables;
+  const componentVariablesInCss = checkMode === 'consumed' ? consumedVariables : new Set([...declaredVariables, ...consumedVariables]);
   const internalVariableSet = new Set(internalVariables);
   const manifestComponentVariables = new Set((manifest.componentVariables || []).map((entry) => entry.name));
   const manifestBaseVariables = new Set((manifest.baseVariables || []).map((entry) => entry.name));
@@ -68,6 +80,10 @@ export function checkManifestVariables({ cssText, manifest, prefix, internalVari
 export async function run(args) {
   const config = getKmwcConfig(args.root);
   const isStrict = !!args.strict;
+  if (!config.cssVariables.isEnabled) {
+    console.log('kmwc check-vars: off (kmwc.cssVariables is false) — nothing to check.');
+    return 0;
+  }
   const manifestPath = resolve(config.root, config.cssVariables.manifest);
   if (!existsSync(manifestPath)) {
     console.log(`kmwc check-vars: no ${config.cssVariables.manifest} — nothing to check.`);
@@ -77,7 +93,7 @@ export async function run(args) {
   const prefix = config.prefix || manifest.prefix;
   if (!prefix) throw new Error('no variable prefix — set kmwc.prefix or "prefix" in the manifest');
 
-  const cssText = config.cssVariables.sources.flatMap((sourcePath) => getStylesheetTexts(resolve(config.root, sourcePath), [])).join('\n');
+  const cssText = config.cssVariables.sources.flatMap((sourcePath) => getStylesheetTexts(resolveSourcePath(config.root, sourcePath), [])).join('\n');
   const verdict = checkManifestVariables({
     cssText,
     manifest,
@@ -86,7 +102,7 @@ export async function run(args) {
     checkMode: config.cssVariables.checkMode,
   });
 
-  const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared';
+  const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared or read';
   const renderSection = (title, names) => `${title} (${names.length}):\n` + names.map((name) => `  --${name}`).join('\n');
   const errors = [];
   const warnings = [];

package/src/cli/commands/doctor.js

@@ -19,27 +19,56 @@ import { spawnSync } from 'node:child_process';
 import { getKmwcConfig, getPortsForBlock, getRegistry, LEGACY_FILES, NON_PAGE_HTML_FILES, PACKAGE_LEAK_RULES, PACKAGE_FILES_EXCLUSIONS } from '../../config.js';
 import { getSyncPlan, getScriptsPlan, CLAUDE_BLOCK_START } from '../sync-plan.js';
 import { checkIsFragment } from '../../vite/page-composer.js';
+import {
+  VALIDATION_NOTES_FILE,
+  loadAcceptedCheckIds,
+  getLibraryOutputMismatches,
+  getLibraryOutputPaths,
+  getLegacyGlobalName,
+  getPortBlockRange,
+  getScriptPortMismatches,
+  loadStalePortMentions,
+  loadSiblingPortCollisions,
+  loadOwnPortsOutsideBlock,
+  loadPlausibleSiteId,
+  loadSharedPlausibleSiteIds,
+  loadKitClassNames,
+  getKitDuplicates,
+} from '../repo-checks.js';
 
 const DEVKIT_PACKAGE_NAME = '@keenmate/web-components-devkit';
+const LOCAL_STYLESHEET_FILE = 'examples-local.css';
 const LEGACY_PAGE_REFERENCES = ['examples-shared.css', 'examples-chapter-nav.js', 'examples-copy-link.js', 'examples-controls-store.js'];
 const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'];
 const PLAYWRIGHT_CONFIG_FILES = ['playwright.config.ts', 'playwright.config.mjs', 'playwright.config.js'];
 
-/** Rulebook suites in the rulebook's canonical reading order; the prefix is passed where the script takes one. */
+/**
+ * Rulebook suites in the rulebook's canonical reading order; the prefix is
+ * passed where the script takes one. `isComponentOnly` suites check what a
+ * custom element ships (its CSS, manifest, overlay) — a `library` (registry
+ * kind, or kmwc.kind) skips them.
+ */
 export const RULEBOOK_SUITES = [
-  { name: 'component-structure', isPrefixed: false },
-  { name: 'naming-conventions', isPrefixed: true },
-  { name: 'css-structure', isPrefixed: true },
-  { name: 'theme-container', isPrefixed: true },
-  { name: 'base-variables', isPrefixed: true },
-  { name: 'color-scheme', isPrefixed: true },
-  { name: 'readme-structure', isPrefixed: false },
-  { name: 'custom-elements-manifest', isPrefixed: false },
-  { name: 'responsive-overlay', isPrefixed: true },
-  { name: 'publish-command', isPrefixed: false },
-  { name: 'example-pages', isPrefixed: false },
+  { name: 'component-structure', isPrefixed: false, isComponentOnly: true },
+  { name: 'naming-conventions', isPrefixed: true, isComponentOnly: false },
+  { name: 'css-structure', isPrefixed: true, isComponentOnly: true },
+  { name: 'theme-container', isPrefixed: true, isComponentOnly: true },
+  { name: 'base-variables', isPrefixed: true, isComponentOnly: true },
+  { name: 'color-scheme', isPrefixed: true, isComponentOnly: true },
+  { name: 'readme-structure', isPrefixed: false, isComponentOnly: false },
+  { name: 'custom-elements-manifest', isPrefixed: false, isComponentOnly: true },
+  { name: 'responsive-overlay', isPrefixed: true, isComponentOnly: true },
+  { name: 'publish-command', isPrefixed: false, isComponentOnly: false },
+  { name: 'example-pages', isPrefixed: false, isComponentOnly: false },
 ];
 
+const LIBRARY_KIND = 'library';
+
+/** The suites that apply to a repo of `kind`. Pure — exported for tests. */
+export function getRulebookSuites(kind) {
+  return RULEBOOK_SUITES.filter((suite) => kind !== LIBRARY_KIND || !suite.isComponentOnly);
+}
+
 function getMajorVersion(versionRange) {
   const match = String(versionRange || '').match(/(\d+)/);
   return match ? Number(match[1]) : null;
@@ -85,7 +114,7 @@ export function checkComponent(config, doctorConfig = {}) {
   } else {
     addPass('config', 'package.json#kmwc present');
     if (!config.packageJson.kmwc.title) addWarning('config', 'kmwc.title not set (falls back to a title-cased id)', 'set kmwc.title');
-    if (!config.prefix) addWarning('config', 'kmwc.prefix not set — rulebook suites run without a CSS prefix', 'set kmwc.prefix to the prefix reserved in base-variables.md');
+    if (!config.prefix && config.kind !== LIBRARY_KIND) addWarning('config', 'kmwc.prefix not set — rulebook suites run without a CSS prefix', 'set kmwc.prefix to the prefix reserved in base-variables.md');
     if (!config.packageJson.kmwc.ports?.dev) addWarning('config', 'kmwc.ports.dev not set (falls back to 5173)', 'take the port from the devkit components.json');
   }
 
@@ -102,6 +131,11 @@ export function checkComponent(config, doctorConfig = {}) {
   if (!viteConfigFile) addError('vite', 'no vite.config.*', 'create one: export default defineComponentConfig()');
   else if (!/defineComponentConfig|createExamplesPlugin/.test(readFileSync(join(config.root, viteConfigFile), 'utf8'))) {
     addError('vite', `${viteConfigFile} doesn't use the devkit preset`, "import { defineComponentConfig } from '@keenmate/web-components-devkit/vite'");
+    // Before the switch: the preset derives the UMD global from kmwc — a silent rename breaks script-tag users.
+    const legacyGlobalName = getLegacyGlobalName(readFileSync(join(config.root, viteConfigFile), 'utf8'));
+    if (legacyGlobalName && config.library.shouldBuild && legacyGlobalName !== config.library.globalName) {
+      addError('vite', `the UMD global is "${legacyGlobalName}" today; the preset would make it "${config.library.globalName}"`, `set kmwc.library.globalName to "${legacyGlobalName}"`);
+    }
   } else addPass('vite', `${viteConfigFile} uses the devkit preset`);
 
   const playwrightConfigFile = getFirstExistingFile(config.root, PLAYWRIGHT_CONFIG_FILES);
@@ -148,6 +182,21 @@ export function checkComponent(config, doctorConfig = {}) {
     );
   }
 
+  // Page CSS that re-implements the kit (a local .kbd after the kit styled <kbd>, inline widths …).
+  const kitClassNames = loadKitClassNames();
+  const localStylesheetPath = join(config.root, LOCAL_STYLESHEET_FILE);
+  const kitDuplicateSources = [
+    ...pageFiles.map((pageFile) => ({ file: pageFile, duplicates: getKitDuplicates(readFileSync(join(config.root, pageFile), 'utf8'), kitClassNames) })),
+    ...(existsSync(localStylesheetPath)
+      ? [{ file: LOCAL_STYLESHEET_FILE, duplicates: getKitDuplicates(readFileSync(localStylesheetPath, 'utf8'), kitClassNames, { isStylesheet: true }) }]
+      : []),
+  ].filter((source) => source.duplicates.length);
+  for (const { file, duplicates } of kitDuplicateSources) {
+    const shownDuplicates = duplicates.slice(0, 3).map((duplicate) => `${duplicate.found} → ${duplicate.advice}`).join('; ');
+    addWarning('pages', `${file}: ${duplicates.length} rule(s) / style(s) the kit already covers — ${shownDuplicates}${duplicates.length > 3 ? ' …' : ''}`, 'use the kit (devkit README "Examples kit")');
+  }
+  if (pageFiles.length && !kitDuplicateSources.length) addPass('pages', 'no page CSS re-implements the kit');
+
   // ── generated files ──────────────────────────────────────────────────────
   if (config.hasPackageConfig) {
     for (const planItem of getSyncPlan(config)) {
@@ -183,12 +232,37 @@ export function checkComponent(config, doctorConfig = {}) {
           `set package.json#kmwc.ports to { "dev": ${registryPorts.dev}, "image": ${registryPorts.image} } (components.json port block ${registryEntry.port})`
         );
       } else addPass('registry', `ports match the registry (dev ${config.ports.dev}, image ${config.ports.image})`);
+      checkPorts(config, registryEntry.port, { addPass, addWarning, addError });
     }
     if (registryEntry.prefix && config.prefix && registryEntry.prefix !== config.prefix) {
       addError('registry', `kmwc.prefix "${config.prefix}" ≠ registry prefix "${registryEntry.prefix}"`, 'use the reserved prefix');
     }
   }
 
+  // ── library output names ─────────────────────────────────────────────────
+  if (config.hasPackageConfig && config.library.shouldBuild) {
+    const outputMismatches = getLibraryOutputMismatches(config.packageJson, config.library);
+    for (const { field, target } of outputMismatches) {
+      addError(
+        'library',
+        `package.json#${field} → ${target}, but the library build emits ${getLibraryOutputPaths(config.library).join(', ')}`,
+        'set kmwc.library.fileName / cssFileName to the published names (or fix the package.json target)'
+      );
+    }
+    if (!outputMismatches.length) addPass('library', 'package.json targets match the library build outputs');
+  }
+
+  // ── analytics ────────────────────────────────────────────────────────────
+  const plausibleSiteId = loadPlausibleSiteId(config.root);
+  const sharingRepoIds = loadSharedPlausibleSiteIds(config, getRegistry(), plausibleSiteId);
+  if (sharingRepoIds.length) {
+    addError(
+      'analytics',
+      `Plausible site id ${plausibleSiteId} is also used by ${sharingRepoIds.join(', ')} — one site's traffic is counted as the other's`,
+      "set kmwc.analytics.plausibleSiteId to this site's own id"
+    );
+  } else if (plausibleSiteId) addPass('analytics', `Plausible site id ${plausibleSiteId} is this repo's own`);
+
   // ── package contents ─────────────────────────────────────────────────────
   if (doctorConfig.shouldCheckPackage !== false) checkPackageContents(config, { addPass, addWarning, addError });
 
@@ -198,6 +272,33 @@ export function checkComponent(config, doctorConfig = {}) {
   return results;
 }
 
+/** Ports: script --port flags, own configs and docs outside the block, siblings inside it. */
+function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
+  const [firstPort, lastPort] = getPortBlockRange(portBlock);
+  const blockLabel = `${firstPort}–${lastPort}`;
+  const scriptPortMismatches = getScriptPortMismatches(config.packageJson.scripts, config.ports);
+  for (const { scriptName, port, expectedPort } of scriptPortMismatches) {
+    addError('ports', `script "${scriptName}" pins --port ${port}; kmwc.ports gives ${expectedPort}`, `drop the --port flag (the preset reads kmwc.ports)`);
+  }
+  const ownStrayPorts = loadOwnPortsOutsideBlock(config, portBlock).filter(({ file }) => !file.startsWith('package.json#scripts.'));
+  for (const { port, file } of ownStrayPorts) addError('ports', `${file} uses port ${port}, outside this repo's block ${blockLabel}`, 'take ports from kmwc.ports (the devkit presets do)');
+  const siblingCollisions = loadSiblingPortCollisions(config, getRegistry());
+  for (const { id, port, file } of siblingCollisions) {
+    addError('ports', `${id} uses port ${port} (${file}) — inside this repo's block ${blockLabel}`, `move ${id} to its own components.json block`);
+  }
+  const stalePortMentions = loadStalePortMentions(config.root, portBlock);
+  if (stalePortMentions.length) {
+    addWarning(
+      'ports',
+      `docs mention ports outside ${blockLabel}: ${stalePortMentions.map(({ file, port }) => `${file} ${port}`).join(', ')}`,
+      `update them to ${getPortsForBlock(portBlock).dev} (dev) / ${getPortsForBlock(portBlock).image} (image)`
+    );
+  }
+  if (!scriptPortMismatches.length && !ownStrayPorts.length && !siblingCollisions.length && !stalePortMentions.length) {
+    addPass('ports', `scripts, configs, docs and sibling repos keep to block ${blockLabel}`);
+  }
+}
+
 /** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
 export function getPackageLeaks(packedPaths) {
   return packedPaths
@@ -248,7 +349,13 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
     return;
   }
   const skippedSuites = new Set(config.rulebook.skippedChecks);
-  for (const suite of RULEBOOK_SUITES) {
+  const acceptedCheckIds = loadAcceptedCheckIds(config.root);
+  const suites = getRulebookSuites(config.kind);
+  if (suites.length < RULEBOOK_SUITES.length) {
+    const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => !suites.includes(suite)).map((suite) => suite.name);
+    addPass('rulebook', `${config.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+  }
+  for (const suite of suites) {
     if (skippedSuites.has(suite.name)) continue;
     if (!existsSync(join(config.rulebook.path, `${suite.name}.checks.sh`))) continue;
     const suiteResult = runRulebookSuite(config, suite);
@@ -263,7 +370,11 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
       continue;
     }
     const failures = getSuiteFailures(suiteResult.stdout);
-    for (const failure of failures) addError(checkName, `${failure.checkId} ${failure.reason}`, `see ${suite.name}.checks.md → ${failure.checkId}`);
+    for (const failure of failures) {
+      // An architectural decision recorded in VALIDATION-NOTES.md (the rulebook's accepted-deviation file).
+      if (acceptedCheckIds.has(failure.checkId)) addPass(checkName, `${failure.checkId} accepted deviation (${VALIDATION_NOTES_FILE}): ${failure.reason}`);
+      else addError(checkName, `${failure.checkId} ${failure.reason}`, `see ${suite.name}.checks.md → ${failure.checkId}`);
+    }
     if (!failures.length) addPass(checkName, suiteResult.status === 0 ? 'all auto checks pass' : `exit ${suiteResult.status}`);
   }
 }
@@ -280,11 +391,13 @@ export async function run(args) {
   }
 
   const LEVEL_ICONS = { pass: '✓', warning: '⚠', error: '✗' };
-  console.log(`kmwc doctor — ${config.packageName} (${config.root})\n`);
+  console.log(`kmwc doctor — ${config.packageName}${config.kind === 'component' ? '' : ` [${config.kind}]`} (${config.root})\n`);
   for (const result of results) {
     if (result.level === 'pass' && !args.verbose) continue;
     console.log(`${LEVEL_ICONS[result.level]} [${result.checkName}] ${result.message}${result.fixHint ? `\n    → ${result.fixHint}` : ''}`);
   }
+  const acceptedCount = results.filter((result) => result.level === 'pass' && result.message.includes(`accepted deviation (${VALIDATION_NOTES_FILE})`)).length;
+  if (acceptedCount && !args.verbose) console.log(`ℹ ${acceptedCount} rulebook failure(s) accepted in ${VALIDATION_NOTES_FILE} (--verbose lists them)`);
   console.log(`\n${errorCount ? '✗' : '✓'} ${errorCount} error(s), ${warningCount} warning(s)${args.verbose ? '' : ' (--verbose lists passing checks)'}`);
   return errorCount ? 1 : 0;
 }

package/src/cli/kmwc.js

@@ -5,62 +5,109 @@
  *   kmwc sync [--check]               regenerate devkit-owned files from package.json#kmwc
  *   kmwc doctor [--json]              check this repo against the devkit + rulebook standard
  *   kmwc check-vars [--strict]        validate component-variables.manifest.json against the CSS
+ *   kmwc check-pages [--url <u>]      every example page in Chromium: errors, undefined elements, overflow
  *   kmwc check-release --tag <tag>    gate a publish (version ⇔ dist-tag, not yet on npm)
  *   kmwc new <name> [options]         scaffold a new component repo next to the devkit
  *   kmwc readme [--check]             regenerate the devkit README catalogue (devkit repo only)
+ *   kmwc <command> --help             that command's usage (never runs it)
  *
  * All commands act on the current directory (override with --root <dir>).
- * Each command module exports `run(args)` returning the process exit code.
+ * Each command module exports `run(args)` returning the process exit code; an
+ * unknown option is an error (exit 2), never ignored.
  */
 import { argv, exit } from 'node:process';
-import { parseArgs } from './args.js';
+import { parseArgs, checkIsHelpRequested } from './args.js';
 
-const COMMAND_LOADERS = {
-  sync: () => import('./commands/sync.js'),
-  doctor: () => import('./commands/doctor.js'),
-  'check-vars': () => import('./commands/check-vars.js'),
-  'check-release': () => import('./commands/check-release.js'),
-  new: () => import('./commands/new.js'),
-  readme: () => import('./commands/readme.js'),
-};
-
-function renderUsage() {
-  console.log(`kmwc — Keenmate web-components devkit
-
-Usage: kmwc <command> [options]
-
-  sync [--check]            Regenerate Dockerfile, nginx.conf, Makefile, .dockerignore,
+/** Every command: its module, the flags it takes and its usage text. */
+const COMMANDS = {
+  sync: {
+    load: () => import('./commands/sync.js'),
+    flags: { booleans: ['check'] },
+    usage: `sync [--check]            Regenerate Dockerfile, nginx.conf, Makefile, .dockerignore,
                             the CLAUDE.md devkit block, .gitignore entries and missing
-                            standard scripts. --check: report drift, write nothing.
-  doctor [--json]           Check this repo against the devkit standard and the
+                            standard scripts. --check: report drift, write nothing.`,
+  },
+  doctor: {
+    load: () => import('./commands/doctor.js'),
+    flags: { booleans: ['json', 'verbose', 'no-rulebook', 'no-pack'] },
+    usage: `doctor [--json]           Check this repo against the devkit standard and the
                             BlissFramework rulebook (*.checks.sh), and that npm pack ships no
-                            dev-only files. --verbose, --no-rulebook, --no-pack.
-  check-vars [--strict]     Validate component-variables.manifest.json against the CSS.
-  check-release --tag <t>   Gate a publish: latest ⇔ release version, rc ⇔ -rcN,
-                            version not on npm yet. --offline skips the npm lookup.
-  new <name>                Scaffold a new component (e.g. \`kmwc new web-colorpicker --prefix cpk\`).
-                            --title "…" --tag … --prefix … --dir … --port … --register
+                            dev-only files. --verbose, --no-rulebook, --no-pack.`,
+  },
+  'check-vars': {
+    load: () => import('./commands/check-vars.js'),
+    flags: { booleans: ['strict'] },
+    usage: `check-vars [--strict]     Validate component-variables.manifest.json against the CSS.`,
+  },
+  'check-pages': {
+    load: () => import('./commands/check-pages.js'),
+    flags: { values: ['url', 'widths'] },
+    usage: `check-pages [--url <u>]   Load every example page in Chromium at 1440 / 390 / 320px and report
+                            page/console errors, failed requests, undefined elements and a page
+                            wider than the viewport. Starts the dev server unless --url is given.
+                            --widths 1440,390,320.`,
+  },
+  'check-release': {
+    load: () => import('./commands/check-release.js'),
+    flags: { booleans: ['offline'], values: ['tag'] },
+    usage: `check-release --tag <t>   Gate a publish: latest ⇔ release version, rc ⇔ -rcN,
+                            version not on npm yet. --offline skips the npm lookup.`,
+  },
+  new: {
+    load: () => import('./commands/new.js'),
+    flags: { booleans: ['register', 'minimal', 'adopt', 'offline'], values: ['title', 'tagline', 'tag', 'prefix', 'dir', 'port'] },
+    usage: `new <name>                Scaffold a new component (e.g. \`kmwc new web-colorpicker --prefix cpk\`).
+                            --title "…" --tagline "…" --tag … --prefix … --dir … --port …
+                            --register --offline
                             --minimal: empty skeleton (no inputs/events) instead of the sample
-                            --adopt: an already registered component (migration scratch scaffold)
-  readme [--check]          Regenerate the README catalogue from components.json (devkit repo).
+                            --adopt: an already registered component (migration scratch scaffold)`,
+  },
+  readme: {
+    load: () => import('./commands/readme.js'),
+    flags: { booleans: ['check'] },
+    usage: `readme [--check]          Regenerate the README catalogue from components.json (devkit repo).`,
+  },
+};
+
+const GLOBAL_USAGE = `Global: --root <dir>        Act on <dir> instead of the current directory.
+        --help, -h          Show the usage (of one command: kmwc <command> --help).`;
 
-Global: --root <dir>        Act on <dir> instead of the current directory.`);
+function renderUsage(commandName) {
+  if (commandName) {
+    console.log(`Usage: kmwc ${COMMANDS[commandName].usage}\n\n${GLOBAL_USAGE}`);
+    return;
+  }
+  const commandLines = Object.values(COMMANDS).map((command) => `  ${command.usage}`).join('\n');
+  console.log(`kmwc — Keenmate web-components devkit\n\nUsage: kmwc <command> [options]\n\n${commandLines}\n\n${GLOBAL_USAGE}`);
 }
 
 async function main() {
   const [commandName, ...commandArgs] = argv.slice(2);
   if (!commandName || ['help', '--help', '-h'].includes(commandName)) {
-    renderUsage();
+    renderUsage(COMMANDS[commandArgs[0]] ? commandArgs[0] : undefined);
     return 0;
   }
-  const loadCommand = COMMAND_LOADERS[commandName];
-  if (!loadCommand) {
+  const command = COMMANDS[commandName];
+  if (!command) {
     console.error(`kmwc: unknown command "${commandName}"\n`);
     renderUsage();
     return 2;
   }
-  const command = await loadCommand();
-  return (await command.run(parseArgs(commandArgs))) ?? 0;
+  // Help never runs the command (`kmwc sync --help` once overwrote a Makefile).
+  if (checkIsHelpRequested(commandArgs)) {
+    renderUsage(commandName);
+    return 0;
+  }
+  let args;
+  try {
+    args = parseArgs(commandArgs, command.flags);
+  } catch (error) {
+    console.error(`kmwc ${commandName}: ${error.message}\n`);
+    renderUsage(commandName);
+    return 2;
+  }
+  const commandModule = await command.load();
+  return (await commandModule.run(args)) ?? 0;
 }
 
 main().then(