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

package/src/cli/commands/readme.js

@@ -0,0 +1,111 @@
+/**
+ * kmwc readme — regenerate the README catalogue from components.json.
+ *
+ * Descriptions and devkit adoption are read from the sibling
+ * checkouts (offline — no npm calls), so the table reflects the working copies
+ * next to this repo. Rewrites only the region between the catalogue markers.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEVKIT_ROOT, getRegistry, getJsonFile, PORT_RANGES } from '../../config.js';
+
+export const CATALOGUE_START = '<!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->';
+export const CATALOGUE_END = '<!-- kmwc:catalogue:end -->';
+
+const DEVKIT_PACKAGE_NAME = '@keenmate/web-components-devkit';
+const SHORT_TEXT_LENGTH = 110;
+
+/** Read the package.json that represents a registry entry (monorepo-aware). */
+function getSiblingPackageInfo(entry) {
+  const repoPath = resolve(DEVKIT_ROOT, entry.path || `../${entry.id}`);
+  if (!existsSync(repoPath)) return { isPresent: false };
+  const rootPackageJsonPath = join(repoPath, 'package.json');
+  const mainPackageJsonPath = [join(repoPath, 'packages', entry.id, 'package.json'), rootPackageJsonPath].find((path) => existsSync(path));
+  const mainPackageJson = mainPackageJsonPath ? getJsonFile(mainPackageJsonPath) : null;
+  const rootPackageJson = existsSync(rootPackageJsonPath) ? getJsonFile(rootPackageJsonPath) : null;
+  const dependencies = { ...rootPackageJson?.dependencies, ...rootPackageJson?.devDependencies };
+  return {
+    isPresent: true,
+    description: mainPackageJson?.description || rootPackageJson?.description || '',
+    isDevkitAdopted: !!(rootPackageJson?.kmwc && dependencies[DEVKIT_PACKAGE_NAME]),
+  };
+}
+
+const mapToTableCell = (text) => String(text ?? '').replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+const renderLink = (label, href) => (href ? `[${label}](${href})` : '');
+const mapToShortText = (text, maxLength = SHORT_TEXT_LENGTH) =>
+  text.length > maxLength ? text.slice(0, maxLength - 1).replace(/\s+\S*$/, '') + '…' : text;
+const renderPackageName = (entry) => (entry.npm ? `\`${entry.npm}\`` : '—');
+const renderPort = (entry) => (entry.port ? String(entry.port) : '—');
+
+export function renderCatalogue(registry = getRegistry()) {
+  const entries = registry.components;
+  const getEntriesOfKind = (kind) => entries.filter((entry) => entry.kind === kind);
+  const lines = [];
+
+  lines.push('### Components', '');
+  lines.push('| Component | Package | Prefix | Dev port | Links | Devkit | About |');
+  lines.push('|---|---|---|---:|---|:---:|---|');
+  for (const entry of getEntriesOfKind('component')) {
+    const siblingInfo = getSiblingPackageInfo(entry);
+    const companions = entries.filter((companion) => ['showcase', 'docs'].includes(companion.kind) && companion.for === entry.id);
+    const links = [
+      renderLink('repo', entry.repo),
+      renderLink('examples', entry.examples),
+      renderLink('docs', entry.docs),
+      ...companions.map((companion) => (companion.url ? renderLink(companion.kind, companion.url) : `\`${companion.id}\``)),
+    ].filter(Boolean);
+    lines.push(
+      `| **${mapToTableCell(entry.id)}** | ${renderPackageName(entry)} | ${entry.prefix ? `\`${entry.prefix}\`` : '—'} | ${renderPort(entry)} | ${links.join(' · ') || '—'} | ${siblingInfo.isDevkitAdopted ? '✅' : '—'} | ${mapToTableCell(mapToShortText(siblingInfo.description || entry.note || ''))} |`
+    );
+  }
+
+  lines.push('', '### Shared libraries', '');
+  lines.push('| Library | Package | Dev port | About |');
+  lines.push('|---|---|---:|---|');
+  for (const entry of getEntriesOfKind('library')) {
+    const siblingInfo = getSiblingPackageInfo(entry);
+    lines.push(`| **${mapToTableCell(entry.id)}** | ${renderPackageName(entry)} | ${renderPort(entry)} | ${mapToTableCell(entry.note || siblingInfo.description)} |`);
+  }
+
+  lines.push('', '### Showcases, docs & test harnesses', '');
+  lines.push('| Repo | Kind | For | Dev port | About |');
+  lines.push('|---|---|---|---:|---|');
+  for (const entry of entries.filter((candidate) => ['showcase', 'docs', 'test'].includes(candidate.kind))) {
+    const about = entry.url ? `${renderLink(entry.url, entry.url)} ${entry.note || ''}` : entry.note || '';
+    lines.push(`| ${mapToTableCell(entry.id)} | ${entry.kind} | ${entry.for || '—'} | ${renderPort(entry)} | ${mapToTableCell(about)} |`);
+  }
+
+  const rangesText = PORT_RANGES.map((range) => `${range.kinds.join(' & ')} ${range.firstBlock}–${range.lastBlock}`).join(' · ');
+  lines.push(
+    '',
+    `**Ports** — a block of 100 per repo: dev server = **Dev port**, preview = +1, examples image = +10. Each kind numbers its blocks by 100 inside its own range (${rangesText}), ` +
+      'so any number of repos run side by side without collisions and a new component lands next to the others. ' +
+      '`kmwc doctor` checks a repo against its block; `kmwc new` takes the next free one.'
+  );
+
+  return lines.join('\n');
+}
+
+export async function run(args) {
+  const readmePath = join(DEVKIT_ROOT, 'README.md');
+  const currentText = readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  const startIndex = currentText.indexOf(CATALOGUE_START);
+  const endIndex = currentText.indexOf(CATALOGUE_END);
+  if (startIndex === -1 || endIndex < startIndex) {
+    throw new Error(`README.md is missing the catalogue markers:\n${CATALOGUE_START}\n${CATALOGUE_END}`);
+  }
+
+  const nextText = currentText.slice(0, startIndex + CATALOGUE_START.length) + '\n' + renderCatalogue() + '\n' + currentText.slice(endIndex);
+  if (nextText === currentText) {
+    console.log('✓ README catalogue up to date');
+    return 0;
+  }
+  if (args.check) {
+    console.log('✗ README catalogue is stale — run `npm run readme`');
+    return 1;
+  }
+  writeFileSync(readmePath, nextText);
+  console.log('✓ README catalogue regenerated');
+  return 0;
+}

package/src/cli/commands/sync.js

@@ -0,0 +1,48 @@
+/**
+ * kmwc sync — bring devkit-owned files in line with package.json#kmwc.
+ * Generated files are overwritten wholesale; CLAUDE.md only inside its managed
+ * block; .gitignore and package.json scripts only gain what's missing (an
+ * existing script is never rewritten — doctor reports the differences).
+ */
+import { writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getKmwcConfig } from '../../config.js';
+import { getSyncPlan, getScriptsPlan } from '../sync-plan.js';
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const isCheckOnly = !!args.check;
+  if (!config.hasPackageConfig) {
+    console.error('kmwc sync: package.json has no "kmwc" section — add one first (see the devkit README).');
+    return 1;
+  }
+
+  const changedItems = getSyncPlan(config).filter((planItem) => planItem.isChanged);
+  const { missingScripts, differingScripts } = getScriptsPlan(config);
+  const missingScriptNames = Object.keys(missingScripts);
+
+  for (const planItem of changedItems) {
+    const action = planItem.currentText == null ? 'create' : 'update';
+    console.log(`${isCheckOnly ? '✗ would' : '✓'} ${action} ${planItem.path}`);
+    if (!isCheckOnly) writeFileSync(join(config.root, planItem.path), planItem.expectedText);
+  }
+
+  if (missingScriptNames.length) {
+    console.log(`${isCheckOnly ? '✗ would add' : '✓ added'} scripts: ${missingScriptNames.join(', ')}`);
+    if (!isCheckOnly) {
+      const packageJsonPath = join(config.root, 'package.json');
+      const packageJsonText = readFileSync(packageJsonPath, 'utf8');
+      const indentation = packageJsonText.match(/^[ \t]+(?=")/m)?.[0] || '  ';
+      const packageJson = JSON.parse(packageJsonText);
+      packageJson.scripts = { ...(packageJson.scripts || {}), ...missingScripts };
+      writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, indentation) + '\n');
+    }
+  }
+
+  for (const [scriptName, difference] of Object.entries(differingScripts)) {
+    console.log(`⚠ script "${scriptName}" is "${difference.currentCommand}" — standard is "${difference.standardCommand}" (left as is)`);
+  }
+
+  if (!changedItems.length && !missingScriptNames.length) console.log('✓ everything in sync');
+  return isCheckOnly && (changedItems.length || missingScriptNames.length) ? 1 : 0;
+}

package/src/cli/kmwc.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * kmwc — the Keenmate web-components devkit CLI.
+ *
+ *   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-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)
+ *
+ * All commands act on the current directory (override with --root <dir>).
+ * Each command module exports `run(args)` returning the process exit code.
+ */
+import { argv, exit } from 'node:process';
+import { parseArgs } 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,
+                            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
+                            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
+                            --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).
+
+Global: --root <dir>        Act on <dir> instead of the current directory.`);
+}
+
+async function main() {
+  const [commandName, ...commandArgs] = argv.slice(2);
+  if (!commandName || ['help', '--help', '-h'].includes(commandName)) {
+    renderUsage();
+    return 0;
+  }
+  const loadCommand = COMMAND_LOADERS[commandName];
+  if (!loadCommand) {
+    console.error(`kmwc: unknown command "${commandName}"\n`);
+    renderUsage();
+    return 2;
+  }
+  const command = await loadCommand();
+  return (await command.run(parseArgs(commandArgs))) ?? 0;
+}
+
+main().then(
+  (exitCode) => exit(exitCode),
+  (error) => {
+    console.error(`kmwc: ${error?.message || error}`);
+    if (process.env.KMWC_DEBUG) console.error(error);
+    exit(1);
+  }
+);

package/src/cli/sync-plan.js

@@ -0,0 +1,163 @@
+/**
+ * The sync plan: what every devkit-owned file in a component SHOULD contain.
+ * `kmwc sync` writes it, `kmwc sync --check` and `kmwc doctor` diff against it
+ * — one computation, so "what sync would do" and "what doctor complains about"
+ * can never disagree.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEVKIT_ROOT } from '../config.js';
+import { renderTemplate } from '../template.js';
+
+export { renderTemplate };
+
+export const GENERATED_MARK = 'GENERATED by `kmwc sync`';
+
+const GENERATED_HEADER =
+  `# ${GENERATED_MARK} from @keenmate/web-components-devkit — do not edit.\n` +
+  `# Change package.json#kmwc (or the devkit template) and re-run \`npx kmwc sync\`.`;
+
+export const CLAUDE_BLOCK_START = '<!-- kmwc:devkit:start — managed by `kmwc sync`, do not edit inside -->';
+export const CLAUDE_BLOCK_END = '<!-- kmwc:devkit:end -->';
+
+/** Files rendered wholesale from templates. */
+export const GENERATED_FILES = [
+  { path: 'Dockerfile', template: 'Dockerfile.tmpl' },
+  { path: 'nginx.conf', template: 'nginx.conf.tmpl' },
+  { path: 'Makefile', template: 'Makefile.tmpl' },
+  { path: '.dockerignore', template: 'dockerignore.tmpl' },
+];
+
+const PLAYWRIGHT_CONFIG_FILES = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs'];
+const CEM_CONFIG_FILE = 'custom-elements-manifest.config.mjs';
+
+export function getTemplate(templateName) {
+  return readFileSync(join(DEVKIT_ROOT, 'templates', templateName), 'utf8');
+}
+
+export function getTemplateVariables(config) {
+  return {
+    HEADER: GENERATED_HEADER,
+    ID: config.id,
+    PACKAGE_NAME: config.packageName,
+    NODE_IMAGE: config.image.nodeImage,
+    INSTALL_COMMAND: config.image.installCommand,
+    COPY_PACKAGE_JSONS: config.image.packageJsonPaths
+      .map((packageJsonPath) => {
+        const targetDirectory = packageJsonPath.includes('/') ? packageJsonPath.slice(0, packageJsonPath.lastIndexOf('/') + 1) : './';
+        return `COPY ${packageJsonPath} ${targetDirectory}`;
+      })
+      .join('\n'),
+    OUT_DIR: config.examples.outDir,
+    RUNNER: config.image.runner,
+    IMAGE_NAME: config.image.name,
+    CONTAINER_NAME: config.image.container,
+    IMAGE_PORT: config.ports.image,
+    DEV_PORT: config.ports.dev,
+    PREVIEW_PORT: config.ports.preview,
+  };
+}
+
+/** A `node -e` one-liner that removes the given paths (works in npm scripts on every OS). */
+function generateRemoveCommand(paths) {
+  return `node -e "for (const p of ${JSON.stringify(paths).replace(/"/g, "'")}) require('fs').rmSync(p,{recursive:true,force:true})"`;
+}
+
+const hasAnyFile = (root, fileNames) => fileNames.some((fileName) => existsSync(join(root, fileName)));
+
+/** Scripts every component should expose (only added when missing). */
+export function getStandardScripts(config) {
+  const scripts = {
+    dev: 'vite',
+    build: 'vite build',
+    'build:examples': 'vite build --mode examples',
+    'preview:examples': 'vite preview --mode examples',
+    'clean:dist': generateRemoveCommand(['dist']),
+    clean: generateRemoveCommand(['dist', config.examples.outDir]),
+    doctor: 'kmwc doctor',
+  };
+  if (existsSync(join(config.root, config.cssVariables.manifest))) scripts['check:vars'] = 'kmwc check-vars';
+  if (existsSync(join(config.root, CEM_CONFIG_FILE))) scripts.analyze = 'cem analyze';
+  if (hasAnyFile(config.root, PLAYWRIGHT_CONFIG_FILES)) {
+    Object.assign(scripts, {
+      'test:e2e': 'playwright test',
+      'test:e2e:ui': 'playwright test --ui',
+      'test:e2e:headed': 'playwright test --headed',
+      'test:e2e:install': 'playwright install chromium',
+    });
+  }
+  return scripts;
+}
+
+/** Insert or replace the managed block in a CLAUDE.md body (creates the file body when absent). */
+export function updateClaudeBlock(claudeMdText) {
+  const block = `${CLAUDE_BLOCK_START}\n${getTemplate('claude-block.md').trim()}\n${CLAUDE_BLOCK_END}`;
+  if (claudeMdText == null) return `# CLAUDE.md\n\n${block}\n`;
+  const startIndex = claudeMdText.indexOf(CLAUDE_BLOCK_START);
+  const endIndex = claudeMdText.indexOf(CLAUDE_BLOCK_END);
+  if (startIndex !== -1 && endIndex > startIndex) {
+    return claudeMdText.slice(0, startIndex) + block + claudeMdText.slice(endIndex + CLAUDE_BLOCK_END.length);
+  }
+  // No block yet: place it right after the first H1 (or at the top).
+  const firstHeading = claudeMdText.match(/^# .*$/m);
+  if (!firstHeading) return `${block}\n\n${claudeMdText}`;
+  const insertIndex = firstHeading.index + firstHeading[0].length;
+  return `${claudeMdText.slice(0, insertIndex)}\n\n${block}\n${claudeMdText.slice(insertIndex)}`;
+}
+
+function getFileTextOrNull(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, 'utf8') : null;
+}
+
+/** Normalize line endings so a CRLF checkout doesn't read as drift. */
+const normalizeLineEndings = (text) => (text == null ? text : text.replace(/\r\n/g, '\n'));
+
+/**
+ * @returns {Array<{ path: string, kind: 'generated'|'claude'|'gitignore', expectedText: string, currentText: string|null, isChanged: boolean }>}
+ */
+export function getSyncPlan(config) {
+  const variables = getTemplateVariables(config);
+  const skippedFiles = new Set(config.sync.skippedFiles);
+  const planItems = [];
+
+  for (const generatedFile of GENERATED_FILES) {
+    if (skippedFiles.has(generatedFile.path)) continue;
+    const expectedText = renderTemplate(getTemplate(generatedFile.template), variables);
+    const currentText = normalizeLineEndings(getFileTextOrNull(join(config.root, generatedFile.path)));
+    planItems.push({ path: generatedFile.path, kind: 'generated', expectedText, currentText, isChanged: currentText !== expectedText });
+  }
+
+  if (!skippedFiles.has('CLAUDE.md')) {
+    const currentText = normalizeLineEndings(getFileTextOrNull(join(config.root, 'CLAUDE.md')));
+    const expectedText = updateClaudeBlock(currentText);
+    planItems.push({ path: 'CLAUDE.md', kind: 'claude', expectedText, currentText, isChanged: currentText !== expectedText });
+  }
+
+  if (!skippedFiles.has('.gitignore')) {
+    const currentText = normalizeLineEndings(getFileTextOrNull(join(config.root, '.gitignore')));
+    const currentLines = (currentText || '').split('\n').map((line) => line.trim());
+    const wantedLines = [`${config.examples.outDir}/`, '.makefile.env'];
+    const missingLines = wantedLines.filter((line) => !currentLines.includes(line) && !currentLines.includes(line.replace(/\/$/, '')));
+    const expectedText = missingLines.length
+      ? (currentText ? currentText.replace(/\n?$/, '\n') : '') + `# kmwc\n${missingLines.join('\n')}\n`
+      : currentText;
+    planItems.push({ path: '.gitignore', kind: 'gitignore', expectedText, currentText, isChanged: missingLines.length > 0 });
+  }
+
+  return planItems;
+}
+
+/** Missing and differing standard scripts. */
+export function getScriptsPlan(config) {
+  const currentScripts = config.packageJson.scripts || {};
+  const standardScripts = getStandardScripts(config);
+  const missingScripts = {};
+  const differingScripts = {};
+  for (const [scriptName, command] of Object.entries(standardScripts)) {
+    if (!(scriptName in currentScripts)) missingScripts[scriptName] = command;
+    else if (['dev', 'build:examples', 'preview:examples'].includes(scriptName) && currentScripts[scriptName] !== command) {
+      differingScripts[scriptName] = { currentCommand: currentScripts[scriptName], standardCommand: command };
+    }
+  }
+  return { missingScripts, differingScripts };
+}

package/src/config.d.ts

@@ -0,0 +1,149 @@
+/** The `kmwc` section of a component's package.json — every field optional (defaults in `mapKmwcConfig`). */
+export interface KmwcPackageConfig {
+  /** Registry id; defaults to the unscoped package name. */
+  id?: string;
+  /** Human title shown on the examples index header. */
+  title?: string;
+  /** One-line pitch under the title; defaults to package.json `description`. */
+  tagline?: string;
+  /** Custom-element tag the package registers. */
+  tag?: string;
+  /** Reserved CSS prefix (base-variables.md "Existing prefixes"), e.g. `ms`. */
+  prefix?: string;
+  library?: {
+    entry?: string;
+    /** UMD global name. */
+    globalName?: string;
+    /** Output basename → `dist/<fileName>.js` + `dist/<fileName>.umd.js`. */
+    fileName?: string;
+    formats?: Array<'es' | 'umd' | 'cjs' | 'iife'>;
+    /** Lib-mode CSS basename (default `style` → dist/style.css). */
+    cssFileName?: string;
+    /** Emit rolled-up `.d.ts` via vite-plugin-dts. */
+    shouldEmitTypes?: boolean;
+    /** Extra vite-plugin-dts config. */
+    typesPluginConfig?: Record<string, unknown>;
+    shouldEmitSourcemap?: boolean;
+    external?: string[];
+  };
+  ports?: { dev?: number; image?: number };
+  theme?: { accentColor?: string; accentEndColor?: string };
+  examples?: {
+    outDir?: string;
+    /** Production origin for copy-link deep links. */
+    canonicalOrigin?: string;
+    /** Extra dirs/files copied verbatim into the examples build (fetched at runtime). */
+    staticPaths?: string[];
+    /** Root HTML files NOT to build as example pages. */
+    excludedPages?: string[];
+    /** localStorage namespace for the controls persistence; defaults to `id`. */
+    storagePrefix?: string;
+  };
+  analytics?: { plausibleSiteId?: string; plausibleHostUrl?: string };
+  image?: {
+    name?: string;
+    container?: string;
+    runner?: 'podman' | 'docker';
+    nodeImage?: string;
+    /** package.json files copied before install (monorepos list workspace manifests). */
+    packageJsonPaths?: string[];
+    installCommand?: string;
+  };
+  cssVariables?: {
+    manifest?: string;
+    /** Directories (stylesheets scanned) or explicit files (any type, e.g. a built bundle). */
+    sources?: string[];
+    /** Prefixed names (without `--`) that are runtime internals, not theming knobs. */
+    internalVariables?: string[];
+    /** `declared`: manifest ⇔ `--x:` declarations; `consumed`: manifest ⇔ `var(--x)` reads. */
+    checkMode?: 'declared' | 'consumed';
+  };
+  rulebook?: {
+    /** Path to BlissFramework `guidelines/web-components` (env KMWC_RULEBOOK_PATH wins). */
+    path?: string;
+    /** Rulebook check suites to skip, e.g. `["responsive-overlay"]`. */
+    skippedChecks?: string[];
+  };
+  sync?: { skippedFiles?: string[] };
+}
+
+export interface KmwcConfig {
+  root: string;
+  hasPackageConfig: boolean;
+  packageJson: Record<string, any>;
+  id: string;
+  packageName: string;
+  version: string;
+  title: string;
+  tagline: string;
+  tag: string;
+  prefix: string;
+  repository: string;
+  homepage: string;
+  author: string;
+  license: string;
+  library: {
+    entry: string;
+    globalName: string;
+    fileName: string;
+    formats: Array<'es' | 'umd' | 'cjs' | 'iife'>;
+    cssFileName: string;
+    shouldEmitTypes: boolean;
+    typesPluginConfig: Record<string, unknown>;
+    shouldEmitSourcemap: boolean;
+    external: string[];
+  };
+  ports: { dev: number; preview: number; image: number };
+  theme: { accentColor: string; accentEndColor: string };
+  examples: {
+    outDir: string;
+    canonicalOrigin: string;
+    staticPaths: string[];
+    excludedPages: string[];
+    storagePrefix: string;
+  };
+  analytics: { plausibleSiteId: string; plausibleHostUrl: string };
+  image: {
+    name: string;
+    container: string;
+    runner: string;
+    nodeImage: string;
+    packageJsonPaths: string[];
+    installCommand: string;
+  };
+  cssVariables: {
+    manifest: string;
+    sources: string[];
+    internalVariables: string[];
+    checkMode: 'declared' | 'consumed';
+  };
+  rulebook: { path: string; skippedChecks: string[] };
+  sync: { skippedFiles: string[] };
+}
+
+export const DEVKIT_ROOT: string;
+export const DEFAULT_RULEBOOK_PATH: string;
+/** The nearest `<ancestor>/BlissFramework/guidelines/web-components` above `startPath`, or null. */
+export function getRulebookPath(startPath: string): string | null;
+export const LEGACY_FILES: string[];
+export const PACKAGE_LEAK_RULES: Array<{ pattern: RegExp; label: string }>;
+export const PACKAGE_FILES_EXCLUSIONS: string[];
+export const NON_PAGE_HTML_FILES: string[];
+export const PORT_BLOCK_SIZE: number;
+export const PORT_RANGES: Array<{ kinds: string[]; firstBlock: number; lastBlock: number }>;
+export const PREVIEW_PORT_OFFSET: number;
+export const IMAGE_PORT_OFFSET: number;
+export function getPortsForBlock(portBlock: number): { dev: number; preview: number; image: number };
+export function getPortRange(kind: string): { kinds: string[]; firstBlock: number; lastBlock: number };
+export function getNextPortBlock(registry?: { components: Array<Record<string, any>> }, kind?: string): number;
+export function getPeerModule(root: string, moduleId: string): any;
+export function loadPeerModule(root: string, moduleId: string): Promise<any>;
+export function getJsonFile(filePath: string): any;
+export function getDevkitPackageJson(): Record<string, any>;
+export function getRegistry(): { components: Array<Record<string, any>> };
+export function getUnscopedName(packageName: string): string;
+export function mapToTitleCase(id: string): string;
+export function mapToPascalCase(id: string): string;
+export function getKmwcConfig(root?: string): KmwcConfig;
+export function mapKmwcConfig(packageJson: Record<string, any>, root?: string): KmwcConfig;
+export function generateBuildDefines(config: KmwcConfig): Record<string, string>;