@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc02

package/src/cli/commands/doctor.js

@@ -0,0 +1,289 @@
+/**
+ * kmwc doctor — check a component repo against the Keenmate standard.
+ *
+ * Two halves:
+ *   1. Devkit checks — drift prevention: every check is something a past
+ *      session did locally that the devkit now owns (a forked helper script, a
+ *      hand-edited Dockerfile, a port picked at random…).
+ *   2. Rulebook checks — runs the BlissFramework `guidelines/web-components/
+ *      *.checks.sh` suites (path: kmwc.rulebook.path / KMWC_RULEBOOK_PATH) and
+ *      reports their FAILs. The rulebook stays the single source of truth; when
+ *      it isn't checked out (or bash is missing) the suites are skipped with a
+ *      warning. `--no-rulebook` skips them on purpose.
+ *
+ * Errors fail (exit 1); warnings don't.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+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';
+
+const DEVKIT_PACKAGE_NAME = '@keenmate/web-components-devkit';
+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. */
+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 },
+];
+
+function getMajorVersion(versionRange) {
+  const match = String(versionRange || '').match(/(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function getFirstExistingFile(root, fileNames) {
+  return fileNames.find((fileName) => existsSync(join(root, fileName))) || null;
+}
+
+/** Strip ANSI colour codes (the suites colour output when they think they're on a TTY). */
+const mapToPlainText = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+
+/**
+ * Parse a suite's output into failures: lines shaped `❌ FAIL <id> — <reason>`.
+ * Exported for tests.
+ */
+export function getSuiteFailures(suiteOutput) {
+  return mapToPlainText(suiteOutput)
+    .split(/\r?\n/)
+    .map((line) => line.match(/FAIL\s+(\S+)\s+[—-]+\s+(.*)$/))
+    .filter(Boolean)
+    .map((match) => ({ checkId: match[1], reason: match[2].trim() }));
+}
+
+function runRulebookSuite(config, suite) {
+  const scriptPath = join(config.rulebook.path, `${suite.name}.checks.sh`).replace(/\\/g, '/');
+  const scriptArgs = [scriptPath, config.root.replace(/\\/g, '/')];
+  if (suite.isPrefixed && config.prefix) scriptArgs.push(config.prefix);
+  return spawnSync('bash', scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+}
+
+/** Run every check; returns [{ level: 'pass'|'warning'|'error', checkName, message, fixHint? }]. */
+export function checkComponent(config, doctorConfig = {}) {
+  const results = [];
+  const addPass = (checkName, message) => results.push({ level: 'pass', checkName, message });
+  const addWarning = (checkName, message, fixHint) => results.push({ level: 'warning', checkName, message, fixHint });
+  const addError = (checkName, message, fixHint) => results.push({ level: 'error', checkName, message, fixHint });
+  const dependencies = { ...config.packageJson.dependencies, ...config.packageJson.devDependencies };
+
+  // ── kmwc section ─────────────────────────────────────────────────────────
+  if (!config.hasPackageConfig) {
+    addError('config', 'package.json has no "kmwc" section', 'add { "kmwc": { "title", "prefix", "ports", … } } — see the devkit README');
+  } 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.packageJson.kmwc.ports?.dev) addWarning('config', 'kmwc.ports.dev not set (falls back to 5173)', 'take the port from the devkit components.json');
+  }
+
+  // ── dependencies ─────────────────────────────────────────────────────────
+  if (!dependencies[DEVKIT_PACKAGE_NAME]) addError('deps', `${DEVKIT_PACKAGE_NAME} is not a devDependency`, `npm i -D ${DEVKIT_PACKAGE_NAME}`);
+  else addPass('deps', `${DEVKIT_PACKAGE_NAME} ${dependencies[DEVKIT_PACKAGE_NAME]}`);
+  const viteMajorVersion = getMajorVersion(dependencies.vite);
+  if (viteMajorVersion == null) addError('deps', 'vite is not a dependency', 'npm i -D vite@^7');
+  else if (viteMajorVersion < 7) addError('deps', `vite ${dependencies.vite} — the standard is ^7`, 'npm i -D vite@^7');
+  else addPass('deps', `vite ${dependencies.vite}`);
+
+  // ── configs use the presets ──────────────────────────────────────────────
+  const viteConfigFile = getFirstExistingFile(config.root, VITE_CONFIG_FILES);
+  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'");
+  } else addPass('vite', `${viteConfigFile} uses the devkit preset`);
+
+  const playwrightConfigFile = getFirstExistingFile(config.root, PLAYWRIGHT_CONFIG_FILES);
+  if (playwrightConfigFile && !/definePlaywrightConfig/.test(readFileSync(join(config.root, playwrightConfigFile), 'utf8'))) {
+    addWarning(
+      'playwright',
+      `${playwrightConfigFile} doesn't use the devkit preset (port may drift from kmwc.ports.dev)`,
+      "import { definePlaywrightConfig } from '@keenmate/web-components-devkit/playwright'"
+    );
+  }
+
+  // ── legacy copies of devkit-owned files ──────────────────────────────────
+  const legacyFiles = LEGACY_FILES.filter((fileName) => existsSync(join(config.root, fileName)));
+  for (const legacyFile of legacyFiles) addError('legacy', `${legacyFile} is a local copy of a devkit-owned file`, 'delete it — the devkit provides it');
+  if (!legacyFiles.length) addPass('legacy', 'no local copies of devkit-owned files');
+
+  const pageFiles = readdirSync(config.root).filter((fileName) => fileName.endsWith('.html') && !NON_PAGE_HTML_FILES.includes(fileName));
+  let legacyPageCount = 0;
+  for (const pageFile of pageFiles) {
+    const pageHtml = readFileSync(join(config.root, pageFile), 'utf8');
+    const legacyReferences = LEGACY_PAGE_REFERENCES.filter((reference) => pageHtml.includes(reference));
+    if (legacyReferences.length) {
+      legacyPageCount++;
+      addError(
+        'pages',
+        `${pageFile} still references ${legacyReferences.join(', ')}`,
+        'remove the <link>/<script> tags (the plugin injects the kit); controls → attachControlsPersistence from the devkit'
+      );
+    }
+  }
+  if (pageFiles.length && !legacyPageCount) addPass('pages', `${pageFiles.length} page(s), none reference legacy helpers`);
+
+  // Pages still carrying their own <head> + header chrome — the copy-paste
+  // that fragment pages (shared layout) remove.
+  const boilerplatePages = pageFiles.filter((pageFile) => {
+    const pageHtml = readFileSync(join(config.root, pageFile), 'utf8');
+    return !checkIsFragment(pageHtml) && /class="back-link"/.test(pageHtml);
+  });
+  if (boilerplatePages.length) {
+    addWarning(
+      'pages',
+      `${boilerplatePages.length} page(s) repeat the head/header boilerplate: ${boilerplatePages.join(', ')}`,
+      'make them fragment pages — <meta name="kmwc:title">, no <html>/<head>/<header> (see the devkit README "Fragment pages")'
+    );
+  }
+
+  // ── generated files ──────────────────────────────────────────────────────
+  if (config.hasPackageConfig) {
+    for (const planItem of getSyncPlan(config)) {
+      if (!planItem.isChanged) {
+        addPass('sync', `${planItem.path} in sync`);
+        continue;
+      }
+      const state = planItem.currentText == null ? 'missing' : 'out of sync (edited locally or template changed)';
+      if (planItem.kind === 'generated') addError('sync', `${planItem.path} ${state}`, 'npx kmwc sync (repo-specific make targets → Makefile.local)');
+      else if (planItem.kind === 'claude') {
+        (planItem.currentText?.includes(CLAUDE_BLOCK_START) ? addWarning : addError)('sync', `CLAUDE.md devkit block ${state}`, 'npx kmwc sync');
+      } else addWarning('sync', `${planItem.path} ${state}`, 'npx kmwc sync');
+    }
+    const { missingScripts, differingScripts } = getScriptsPlan(config);
+    if (Object.keys(missingScripts).length) addWarning('scripts', `missing standard scripts: ${Object.keys(missingScripts).join(', ')}`, 'npx kmwc sync');
+    for (const [scriptName, difference] of Object.entries(differingScripts)) {
+      addWarning('scripts', `"${scriptName}" is "${difference.currentCommand}", standard is "${difference.standardCommand}"`);
+    }
+  }
+
+  // ── registry cross-check ─────────────────────────────────────────────────
+  const registryEntry = getRegistry().components.find((component) => component.id === config.id);
+  if (!registryEntry) {
+    addWarning('registry', `"${config.id}" is not in the devkit components.json`, 'add an entry (README catalogue + port allocation)');
+  } else {
+    if (registryEntry.port) {
+      const registryPorts = getPortsForBlock(registryEntry.port);
+      const mismatchedPorts = ['dev', 'image'].filter((portName) => registryPorts[portName] !== config.ports[portName]);
+      if (mismatchedPorts.length) {
+        addError(
+          'registry',
+          mismatchedPorts.map((portName) => `ports.${portName} ${config.ports[portName]} ≠ registry ${registryPorts[portName]}`).join('; '),
+          `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})`);
+    }
+    if (registryEntry.prefix && config.prefix && registryEntry.prefix !== config.prefix) {
+      addError('registry', `kmwc.prefix "${config.prefix}" ≠ registry prefix "${registryEntry.prefix}"`, 'use the reserved prefix');
+    }
+  }
+
+  // ── package contents ─────────────────────────────────────────────────────
+  if (doctorConfig.shouldCheckPackage !== false) checkPackageContents(config, { addPass, addWarning, addError });
+
+  // ── rulebook suites ──────────────────────────────────────────────────────
+  if (doctorConfig.shouldRunRulebook !== false) checkRulebook(config, { addPass, addWarning, addError });
+
+  return results;
+}
+
+/** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
+export function getPackageLeaks(packedPaths) {
+  return packedPaths
+    .map((packedPath) => packedPath.replace(/\\/g, '/').replace(/^package\//, ''))
+    .flatMap((packedPath) => {
+      const leakRule = PACKAGE_LEAK_RULES.find((rule) => rule.pattern.test(packedPath));
+      return leakRule ? [{ path: packedPath, label: leakRule.label }] : [];
+    });
+}
+
+/** The file list `npm publish` would ship (no lifecycle scripts, nothing written). */
+function getPackedPaths(config) {
+  const packResult = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
+    cwd: config.root,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (packResult.error || packResult.status !== 0) return null;
+  const packReport = JSON.parse(packResult.stdout.slice(packResult.stdout.indexOf('[')));
+  return packReport[0].files.map((file) => file.path);
+}
+
+function checkPackageContents(config, { addPass, addWarning, addError }) {
+  let packedPaths;
+  try {
+    packedPaths = getPackedPaths(config);
+  } catch {
+    packedPaths = null;
+  }
+  if (!packedPaths) {
+    addWarning('package', 'npm pack --dry-run failed — package contents not checked');
+    return;
+  }
+  const packageLeaks = getPackageLeaks(packedPaths);
+  for (const packageLeak of packageLeaks) {
+    addError(
+      'package',
+      `${packageLeak.path} would be published (${packageLeak.label})`,
+      `exclude it in package.json "files" (e.g. ${PACKAGE_FILES_EXCLUSIONS.map((exclusion) => `"${exclusion}"`).join(', ')}) or narrow the glob`
+    );
+  }
+  if (!packageLeaks.length) addPass('package', `${packedPaths.length} packed file(s), no dev-only files`);
+}
+
+function checkRulebook(config, { addPass, addWarning, addError }) {
+  if (!existsSync(config.rulebook.path)) {
+    addWarning('rulebook', `rulebook not found at ${config.rulebook.path} — rulebook checks skipped`, 'check out BlissFramework or set KMWC_RULEBOOK_PATH / kmwc.rulebook.path');
+    return;
+  }
+  const skippedSuites = new Set(config.rulebook.skippedChecks);
+  for (const suite of RULEBOOK_SUITES) {
+    if (skippedSuites.has(suite.name)) continue;
+    if (!existsSync(join(config.rulebook.path, `${suite.name}.checks.sh`))) continue;
+    const suiteResult = runRulebookSuite(config, suite);
+    if (suiteResult.error) {
+      addWarning('rulebook', `cannot run bash (${suiteResult.error.code}) — rulebook checks skipped`, 'install Git Bash / run from a POSIX shell');
+      return;
+    }
+    const checkName = `rulebook:${suite.name}`;
+    if (suiteResult.status === 2) {
+      const reason = mapToPlainText(suiteResult.stderr || suiteResult.stdout).trim().split(/\r?\n/)[0];
+      addWarning(checkName, `suite could not run: ${reason}`);
+      continue;
+    }
+    const failures = getSuiteFailures(suiteResult.stdout);
+    for (const failure of failures) 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}`);
+  }
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const results = checkComponent(config, { shouldRunRulebook: !args['no-rulebook'], shouldCheckPackage: !args['no-pack'] });
+  const errorCount = results.filter((result) => result.level === 'error').length;
+  const warningCount = results.filter((result) => result.level === 'warning').length;
+
+  if (args.json) {
+    console.log(JSON.stringify({ id: config.id, errorCount, warningCount, results }, null, 2));
+    return errorCount ? 1 : 0;
+  }
+
+  const LEVEL_ICONS = { pass: '✓', warning: '⚠', error: '✗' };
+  console.log(`kmwc doctor — ${config.packageName} (${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}` : ''}`);
+  }
+  console.log(`\n${errorCount ? '✗' : '✓'} ${errorCount} error(s), ${warningCount} warning(s)${args.verbose ? '' : ' (--verbose lists passing checks)'}`);
+  return errorCount ? 1 : 0;
+}

package/src/cli/commands/new.js

@@ -0,0 +1,323 @@
+/**
+ * kmwc new <name> — scaffold a component repo in the rulebook shape.
+ *
+ *   kmwc new web-colorpicker --prefix cpk [--title "Web Color Picker"] [--tag web-colorpicker]
+ *        [--dir ../web-colorpicker] [--port 13200] [--minimal] [--register] [--offline]
+ *   kmwc new web-editor --adopt --dir /tmp/web-editor [--prefix …]
+ *
+ * Default: a small working sample (a toggle with `label` / `active` inputs and
+ * a `change` event) to rename or replace. `--minimal`: an empty skeleton — no
+ * inputs, no events, a slotted root, stub feature CSS — with the same
+ * structure and the same passing rulebook checks.
+ *
+ * Runs the intake (component-intake.md): the npm name must be free, and the
+ * CSS prefix must be 2–4 lowercase letters not reserved in the rulebook's
+ * base-variables.md table or in components.json. A prefix is derived only for
+ * hyphen-separated names (initials) or short single words (tech letter + first
+ * letter); anything ambiguous needs --prefix, because word count is a meaning
+ * question ("daterangepicker" is three words) a script can't answer.
+ *
+ * Produces Element / Logic / Side-layer sources, the canonical CSS set, a
+ * Custom Elements Manifest config, README + docs/, CHANGELOG, LICENSE,
+ * `.claude/commands/publish.md`, examples, fixtures + e2e specs, then the
+ * `kmwc sync` files. The port block (dev = block, image = +10) is the next free
+ * one in the component range (see PORT_RANGES in config.js; `--port` overrides).
+ *
+ * `--adopt` is for MIGRATING a component that is already registered: the id must
+ * be in components.json, the port block (and prefix, unless the entry has none —
+ * then `--prefix`) come from its entry, the npm-name check is skipped (the package
+ * may exist), and the registry is left alone. Scaffold into a scratch `--dir`,
+ * then move the component's own code into the generated shape.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  DEFAULT_RULEBOOK_PATH,
+  DEVKIT_ROOT,
+  getDevkitPackageJson,
+  getJsonFile,
+  getNextPortBlock,
+  getPortsForBlock,
+  getRegistry,
+  PORT_BLOCK_SIZE,
+  PACKAGE_FILES_EXCLUSIONS,
+  getUnscopedName,
+  mapToPascalCase,
+} from '../../config.js';
+import { renderTemplate } from '../sync-plan.js';
+import { run as runSync } from './sync.js';
+
+const SCAFFOLD_ROOT = join(DEVKIT_ROOT, 'templates', 'new');
+/** --minimal: rendered over the full scaffold, replacing only the files that differ. */
+const MINIMAL_OVERLAY_ROOT = join(DEVKIT_ROOT, 'templates', 'new-minimal');
+const PREFIX_PATTERN = /^[a-z]{2,4}$/;
+/** Prefixes used outside component CSS that must not be taken either. */
+const INFRASTRUCTURE_PREFIXES = ['kmwc', 'base'];
+const SHORT_SINGLE_WORD_LENGTH = 6;
+/** Template file names → generated names. */
+const FILE_NAME_PLACEHOLDERS = { _gitignore: '.gitignore' };
+
+/** Prefixes reserved in the rulebook (base-variables.md "Existing prefixes" table) — empty when not checked out. */
+export function getRulebookPrefixes(rulebookPath = DEFAULT_RULEBOOK_PATH) {
+  const baseVariablesPath = join(rulebookPath, 'base-variables.md');
+  if (!existsSync(baseVariablesPath)) return [];
+  const tableRows = readFileSync(baseVariablesPath, 'utf8').matchAll(/^\|\s*`@keenmate\/[^`]+`\s*\|\s*`([a-z]+)`\s*\|/gm);
+  return [...new Set([...tableRows].map((match) => match[1]))];
+}
+
+export function getReservedPrefixes(registry = getRegistry(), rulebookPath = DEFAULT_RULEBOOK_PATH) {
+  const registryPrefixes = registry.components.map((entry) => entry.prefix).filter(Boolean);
+  return new Set([...getRulebookPrefixes(rulebookPath), ...registryPrefixes, ...INFRASTRUCTURE_PREFIXES]);
+}
+
+/**
+ * component-intake.md "C — CSS prefix derivation", for the cases a script can
+ * decide. Returns null when the word count is ambiguous (the caller asks for --prefix).
+ */
+export function generatePrefix(componentId) {
+  const nameWords = componentId.replace(/^(web|svelte)-/, '').split('-').filter(Boolean);
+  const techLetter = componentId.startsWith('svelte-') ? 's' : 'w';
+  if (nameWords.length > 1) return nameWords.map((word) => word[0]).join('');
+  if (nameWords[0].length <= SHORT_SINGLE_WORD_LENGTH) return techLetter + nameWords[0][0];
+  return null;
+}
+
+/** Error message for an unusable prefix, or null. */
+export function checkPrefix(prefix, reservedPrefixes) {
+  if (!PREFIX_PATTERN.test(prefix)) return `prefix "${prefix}" must be 2–4 lowercase letters (component-intake.md)`;
+  if (reservedPrefixes.has(prefix)) return `prefix "${prefix}" is already reserved — pick another (base-variables.md "Existing prefixes")`;
+  return null;
+}
+
+function checkIsPackageNameTaken(packageName) {
+  const result = spawnSync('npm', ['view', packageName, 'name'], { encoding: 'utf8', shell: true });
+  return result.status === 0 && result.stdout.trim() === packageName;
+}
+
+function getFilesRecursive(directoryPath, filePaths = []) {
+  for (const entryName of readdirSync(directoryPath)) {
+    const entryPath = join(directoryPath, entryName);
+    if (statSync(entryPath).isDirectory()) getFilesRecursive(entryPath, filePaths);
+    else filePaths.push(entryPath);
+  }
+  return filePaths;
+}
+
+/** Render every template under `templateRoot` into `targetPath` (later calls overwrite earlier files). */
+function writeScaffoldFiles(templateRoot, targetPath, variables, featureName) {
+  for (const templatePath of getFilesRecursive(templateRoot)) {
+    const relativePath = relative(templateRoot, templatePath)
+      .replace(/__FEATURE__/g, featureName)
+      .split(/[\\/]/)
+      .map((segment) => FILE_NAME_PLACEHOLDERS[segment] || segment)
+      .join('/');
+    const targetFilePath = join(targetPath, relativePath);
+    mkdirSync(dirname(targetFilePath), { recursive: true });
+    writeFileSync(targetFilePath, renderTemplate(readFileSync(templatePath, 'utf8'), variables));
+  }
+}
+
+export function generatePackageJson({ componentId, packageName, tagline, tag, prefix, title, devPort, coreVersion, devkitVersion, logicClass }) {
+  return {
+    name: packageName,
+    version: '0.1.0',
+    description: tagline,
+    type: 'module',
+    license: 'MIT',
+    author: 'Keenmate s.r.o.',
+    homepage: `https://github.com/keenmate/${componentId}`,
+    repository: { type: 'git', url: `git+https://github.com/keenmate/${componentId}.git` },
+    keywords: ['web-components', 'custom-elements', 'keenmate', 'bliss', tag],
+    main: `./dist/${componentId}.umd.js`,
+    module: `./dist/${componentId}.js`,
+    types: './dist/index.d.ts',
+    customElements: 'custom-elements.json',
+    'web-types': 'web-types.json',
+    exports: {
+      '.': { types: './dist/index.d.ts', import: `./dist/${componentId}.js`, require: `./dist/${componentId}.umd.js` },
+      './style.css': './dist/style.css',
+      './manifest': './component-variables.manifest.json',
+      './component-variables.manifest.json': './component-variables.manifest.json',
+      './custom-elements.json': './custom-elements.json',
+      './package.json': './package.json',
+    },
+    files: [
+      'dist',
+      'docs',
+      'component-variables.manifest.json',
+      'custom-elements.json',
+      'web-types.json',
+      'vscode.html-custom-data.json',
+      'vscode.css-custom-data.json',
+      // Never ship AI-assistant guidance, even if a directory above gets added.
+      ...PACKAGE_FILES_EXCLUSIONS,
+    ],
+    sideEffects: ['./dist/*.js', './dist/*.css', './src/index.ts', './src/web-component.ts', './src/css/*.css'],
+    kmwc: {
+      title,
+      tagline,
+      tag,
+      prefix,
+      library: { globalName: logicClass, fileName: componentId },
+      ports: { dev: devPort, image: getPortsForBlock(devPort).image },
+    },
+    scripts: {
+      dev: 'vite',
+      analyze: 'cem analyze',
+      build: 'npm run check:vars && npm run analyze && tsc --noEmit && vite build',
+      'build:examples': 'vite build --mode examples',
+      'preview:examples': 'vite preview --mode examples',
+      typecheck: 'tsc --noEmit',
+      'check:vars': 'kmwc check-vars --strict',
+      doctor: 'kmwc doctor',
+      prepublishOnly: 'npm run clean:dist && npm run build',
+    },
+    dependencies: {
+      '@keenmate/web-components-core': `^${coreVersion}`,
+    },
+    devDependencies: {
+      '@custom-elements-manifest/analyzer': '^0.11.0',
+      '@keenmate/web-components-devkit': `^${devkitVersion}`,
+      '@playwright/test': '^1.60.0',
+      'custom-element-jet-brains-integration': '^1.7.0',
+      'custom-element-vs-code-integration': '^1.5.0',
+      typescript: '^5.9.3',
+      vite: '^7.3.7',
+    },
+  };
+}
+
+export async function run(args) {
+  const requestedName = args._[0];
+  if (!requestedName) {
+    throw new Error('usage: kmwc new <name> --prefix <2-4 letters> [--title "…"] [--tag …] [--dir …] [--port …] [--register] [--offline] [--adopt]');
+  }
+
+  const unscopedName = getUnscopedName(requestedName);
+  const componentId = unscopedName.startsWith('web-') ? unscopedName : `web-${unscopedName}`;
+  const packageName = `@keenmate/${componentId}`;
+  const tag = args.tag || componentId;
+  if (!/^[a-z][a-z0-9]*-[a-z0-9-]+$/.test(tag)) throw new Error(`"${tag}" is not a valid custom-element tag (needs a dash)`);
+  const featureName = tag.replace(/^web-/, '');
+  const elementClass = `${mapToPascalCase(featureName)}Element`;
+  const logicClass = mapToPascalCase(componentId);
+  const title = args.title || mapToPascalCase(componentId).replace(/^Web/, 'Web ');
+  const tagline = args.tagline || `${title} — a framework-agnostic web component.`;
+  const targetPath = resolve(args.dir || join(DEVKIT_ROOT, '..', componentId));
+
+  // ── intake ───────────────────────────────────────────────────────────────
+  const registry = getRegistry();
+  const isAdopting = !!args.adopt;
+  const adoptedEntry = registry.components.find((entry) => entry.id === componentId);
+  if (isAdopting && !adoptedEntry) throw new Error(`--adopt: "${componentId}" is not in components.json — register it, or drop --adopt for a new component`);
+  if (!isAdopting && adoptedEntry) throw new Error(`"${componentId}" is already in components.json (migrating it? add --adopt)`);
+  if (isAdopting && args.register) throw new Error('--adopt never edits the registry — drop --register');
+  if (existsSync(targetPath) && readdirSync(targetPath).length) throw new Error(`${targetPath} exists and is not empty`);
+
+  if (isAdopting && adoptedEntry.prefix && args.prefix && args.prefix !== adoptedEntry.prefix) {
+    throw new Error(`--prefix ${args.prefix} ≠ the registered prefix "${adoptedEntry.prefix}"`);
+  }
+  const prefix = (isAdopting && adoptedEntry.prefix) || args.prefix || generatePrefix(componentId);
+  if (!prefix) {
+    throw new Error(
+      `cannot derive a CSS prefix for "${componentId}" — is "${featureName}" one English word or several? ` +
+        `Pass --prefix (initials of each word, e.g. daterangepicker → drp; component-intake.md "C — CSS prefix derivation").`
+    );
+  }
+  // An adopted component's own registered prefix isn't a clash with itself.
+  const reservedPrefixes = getReservedPrefixes(registry);
+  if (isAdopting && adoptedEntry.prefix) reservedPrefixes.delete(adoptedEntry.prefix);
+  const prefixError = checkPrefix(prefix, reservedPrefixes);
+  if (prefixError) throw new Error(prefixError);
+
+  if (!isAdopting && !args.offline && checkIsPackageNameTaken(packageName)) throw new Error(`${packageName} already exists on npm (component-intake.md "B")`);
+
+  if (isAdopting && args.port && Number(args.port) !== adoptedEntry.port) throw new Error(`--port ${args.port} ≠ the registered port block ${adoptedEntry.port}`);
+  const devPort = isAdopting ? adoptedEntry.port : Number(args.port) || getNextPortBlock(registry);
+  if (devPort % PORT_BLOCK_SIZE !== 0) throw new Error(`--port ${devPort} is not a port block (a multiple of ${PORT_BLOCK_SIZE})`);
+  const portOwner = registry.components.find((entry) => entry.port === devPort && entry.id !== componentId);
+  if (portOwner) throw new Error(`port block ${devPort} belongs to ${portOwner.id} — omit --port to take the next free block`);
+  const corePackageJsonPath = join(DEVKIT_ROOT, '..', 'web-components-core', 'package.json');
+  const coreVersion = existsSync(corePackageJsonPath) ? getJsonFile(corePackageJsonPath).version : '1.0.0-rc12';
+  const today = new Date().toISOString().slice(0, 10);
+
+  const variables = {
+    ID: componentId,
+    TAG: tag,
+    FEATURE: featureName,
+    ELEMENT_CLASS: elementClass,
+    LOGIC_CLASS: logicClass,
+    CONFIG_TYPE: `${mapToPascalCase(featureName)}Config`,
+    EVENT_DETAIL_TYPE: `${mapToPascalCase(featureName)}EventDetail`,
+    EVENTS_TYPE: `${mapToPascalCase(featureName)}Events`,
+    PREFIX: prefix,
+    LOG_NAME: featureName.replace(/-/g, '_').toUpperCase(),
+    TITLE: title,
+    TITLE_UPPER: title.toUpperCase(),
+    TAGLINE: tagline,
+    PACKAGE_NAME: packageName,
+    FILE_NAME: componentId,
+    VERSION: '0.1.0',
+    TODAY: today,
+    YEAR: today.slice(0, 4),
+    DEV_PORT: devPort,
+  };
+
+  // ── scaffold files ───────────────────────────────────────────────────────
+  const isMinimal = !!args.minimal;
+  writeScaffoldFiles(SCAFFOLD_ROOT, targetPath, variables, featureName);
+  if (isMinimal) writeScaffoldFiles(MINIMAL_OVERLAY_ROOT, targetPath, variables, featureName);
+
+  const packageJson = generatePackageJson({
+    componentId,
+    packageName,
+    tagline,
+    tag,
+    prefix,
+    title,
+    devPort,
+    coreVersion,
+    devkitVersion: getDevkitPackageJson().version,
+    logicClass,
+  });
+  writeFileSync(join(targetPath, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
+  console.log(`✓ scaffolded ${componentId}${isMinimal ? ' (minimal)' : ''} in ${targetPath} (prefix ${prefix}, dev port ${devPort})`);
+
+  // ── generated files (Dockerfile, Makefile, CLAUDE.md block, scripts) ─────
+  await runSync({ root: targetPath });
+
+  // ── registry ─────────────────────────────────────────────────────────────
+  const registryEntry = {
+    id: componentId,
+    kind: 'component',
+    prefix,
+    path: relative(DEVKIT_ROOT, targetPath).replace(/\\/g, '/'),
+    npm: packageName,
+    repo: `https://github.com/keenmate/${componentId}`,
+    port: devPort,
+  };
+  if (isAdopting) {
+    if (!adoptedEntry.prefix) console.log(`
+The registry entry has no prefix — add "prefix": "${prefix}" to its components.json entry.`);
+  } else if (args.register) {
+    const registryPath = join(DEVKIT_ROOT, 'components.json');
+    const registryJson = getJsonFile(registryPath);
+    const lastComponentIndex = registryJson.components.map((entry) => entry.kind).lastIndexOf('component');
+    registryJson.components.splice(lastComponentIndex + 1, 0, registryEntry);
+    writeFileSync(registryPath, JSON.stringify(registryJson, null, 2) + '\n');
+    console.log('✓ registered in components.json — run `npm run readme` in the devkit to refresh the catalogue');
+  } else {
+    console.log(`\nAdd it to the devkit registry (components.json), or re-run with --register:\n${JSON.stringify(registryEntry, null, 2)}`);
+  }
+
+  console.log(
+    `\nNext:\n` +
+      `  1. Reserve the prefix "${prefix}" in BlissFramework guidelines/web-components/base-variables.md (and component-intake.md).\n` +
+      `  2. cd ${relative(process.cwd(), targetPath) || '.'} && npm install\n` +
+      `  3. npm run build        # check:vars + CEM analyze + typecheck + vite — commit the generated custom-elements.json & co.\n` +
+      `  4. npm run dev          # http://localhost:${devPort}\n` +
+      `  5. npx kmwc doctor`
+  );
+  return 0;
+}