@revikornmann/muka-ui 0.2.1

package/cli/bin/muka-ui.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Muka UI CLI
+ *
+ * Commands:
+ *   init              - Set up a project to use Muka UI
+ *   install-skill     - Copy shipped skills into .claude/skills (e.g. /setup-muka)
+ *   brand init <name> - Scaffold a custom brand override
+ *   link [path]       - Set up npm link for local development
+ *   components        - List available components
+ */
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+const commandArgs = args.slice(1);
+
+// Help text
+const HELP = `
+Muka UI CLI
+
+Usage:
+  muka-ui <command> [options]
+
+Commands:
+  init              Set up project for Muka UI (creates CLAUDE.md, guidelines)
+  install-skill     Copy shipped skills into .claude/skills (e.g. /setup-muka)
+  brand init <name> Scaffold a custom brand (T2 tokens, manifest, build script)
+  link [path]       Set up npm link for local muka-ui development
+  components        List available Muka UI components
+
+Options:
+  --help, -h        Show this help message
+  --version, -v     Show version
+
+Examples:
+  npx muka-ui init
+  npx muka-ui install-skill
+  npx muka-ui brand init fscl
+  npx muka-ui link /path/to/muka
+  npx muka-ui components
+`;
+
+// Version from package.json
+function getVersion() {
+  const pkg = require('../../package.json');
+  return pkg.version;
+}
+
+// Main entry point
+async function main() {
+  // Handle flags
+  if (!command || command === '--help' || command === '-h') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(`muka-ui v${getVersion()}`);
+    process.exit(0);
+  }
+
+  // Route to command handlers
+  try {
+    switch (command) {
+      case 'init': {
+        const init = require('../commands/init');
+        await init(commandArgs);
+        break;
+      }
+      case 'install-skill': {
+        const installSkill = require('../commands/install-skill');
+        await installSkill(commandArgs);
+        break;
+      }
+      case 'link': {
+        const link = require('../commands/link');
+        await link(commandArgs);
+        break;
+      }
+      case 'brand': {
+        const brand = require('../commands/brand');
+        await brand(commandArgs);
+        break;
+      }
+      case 'components': {
+        const components = require('../commands/components');
+        await components(commandArgs);
+        break;
+      }
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/cli/commands/brand.js

@@ -0,0 +1,198 @@
+/**
+ * `muka-ui brand init <name>` command
+ *
+ * Scaffolds everything a consumer repo needs to host its own brand:
+ * - brand/ directory with T2 alias token files (fonts.json, light.json, dark.json)
+ * - Brand manifest (brand/muka.brand.json)
+ * - Build script (brand/build.js)
+ * - npm script in package.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  fileExists,
+  ensureDir,
+  writeFile,
+  confirm,
+  findProjectRoot,
+  readPackageJson
+} = require('../lib/fs-utils');
+
+/**
+ * Read a wireframe brand file as a template
+ */
+function readBrandTemplate(filename) {
+  const templatePath = path.join(__dirname, '../../tokens/t2-alias/brand/wireframe', filename);
+  return JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+}
+
+/**
+ * Generate the brand manifest for a consumer repo
+ */
+function generateManifest(brandName) {
+  const t1 = 'node_modules/muka-ui/tokens/t1-primitives/**/*.json';
+  const base = 'node_modules/muka-ui/tokens/t2-alias/base.json';
+  const fonts = `brand/fonts.json`;
+  const layout = 'node_modules/muka-ui/tokens/t2-alias/layout/mobile.json';
+  const semantics = 'node_modules/muka-ui/tokens/t3-semantics/ui.json';
+  const components = 'node_modules/muka-ui/tokens/t4-components/**/*.json';
+
+  return {
+    themes: {
+      [`${brandName}-light`]: [
+        t1, base, fonts, `brand/light.json`,
+        layout, semantics, components
+      ],
+      [`${brandName}-dark`]: [
+        t1, base, fonts, `brand/dark.json`,
+        layout, semantics, components
+      ]
+    },
+    breakpoints: {
+      md: 'node_modules/muka-ui/tokens/t2-alias/layout/tablet.json',
+      lg: 'node_modules/muka-ui/tokens/t2-alias/layout/desktop.json'
+    }
+  };
+}
+
+/**
+ * Generate the build script content
+ */
+function generateBuildScript() {
+  return `const path = require('path');
+const TokenBuilder = require('muka-ui/build');
+const manifest = require('./muka.brand.json');
+
+const builder = new TokenBuilder({ rootDir: path.resolve(__dirname, '..') });
+builder.loadManifest(manifest);
+builder.build();
+`;
+}
+
+/**
+ * Main brand command
+ */
+async function brand(args) {
+  const subcommand = args[0];
+
+  if (subcommand !== 'init') {
+    console.error(`Unknown brand subcommand: ${subcommand}`);
+    console.log('\nUsage: muka-ui brand init <name>\n');
+    process.exit(1);
+  }
+
+  const brandName = args[1];
+  if (!brandName) {
+    console.error('Brand name is required.');
+    console.log('\nUsage: muka-ui brand init <name>');
+    console.log('Example: muka-ui brand init fscl\n');
+    process.exit(1);
+  }
+
+  // Validate brand name (lowercase, alphanumeric, hyphens)
+  if (!/^[a-z][a-z0-9-]*$/.test(brandName)) {
+    console.error('Brand name must be lowercase, start with a letter, and contain only letters, numbers, and hyphens.');
+    process.exit(1);
+  }
+
+  console.log(`\n🎨 Muka UI Brand Setup: ${brandName}\n`);
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Could not find package.json. Are you in a Node.js project?');
+  }
+
+  console.log(`Project: ${projectRoot}\n`);
+
+  // --- brand/ directory with token files ---
+  const brandDir = path.join(projectRoot, 'brand');
+  ensureDir(brandDir);
+
+  const tokenFiles = ['fonts.json', 'light.json', 'dark.json'];
+  for (const filename of tokenFiles) {
+    const filePath = path.join(brandDir, filename);
+    if (fileExists(filePath)) {
+      const overwrite = await confirm(`brand/${filename} already exists. Overwrite?`);
+      if (!overwrite) {
+        console.log(`   ⏭ Skipped ${filename}`);
+        continue;
+      }
+    }
+    const template = readBrandTemplate(filename);
+    writeFile(filePath, JSON.stringify(template, null, 2) + '\n');
+    console.log(`   ✓ Created brand/${filename}`);
+  }
+
+  // --- Brand manifest ---
+  const manifestPath = path.join(brandDir, 'muka.brand.json');
+  if (fileExists(manifestPath)) {
+    const overwrite = await confirm('brand/muka.brand.json already exists. Overwrite?');
+    if (!overwrite) {
+      console.log('   ⏭ Skipped muka.brand.json');
+    } else {
+      const manifest = generateManifest(brandName);
+      writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+      console.log('   ✓ Created brand/muka.brand.json');
+    }
+  } else {
+    const manifest = generateManifest(brandName);
+    writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    console.log('   ✓ Created brand/muka.brand.json');
+  }
+
+  // --- Build script ---
+  const buildScriptPath = path.join(brandDir, 'build.js');
+  if (fileExists(buildScriptPath)) {
+    const overwrite = await confirm('brand/build.js already exists. Overwrite?');
+    if (!overwrite) {
+      console.log('   ⏭ Skipped build script');
+    } else {
+      writeFile(buildScriptPath, generateBuildScript());
+      console.log('   ✓ Created brand/build.js');
+    }
+  } else {
+    writeFile(buildScriptPath, generateBuildScript());
+    console.log('   ✓ Created brand/build.js');
+  }
+
+  // --- Add npm script to package.json ---
+  const pkg = readPackageJson(projectRoot);
+  if (pkg) {
+    if (!pkg.scripts) pkg.scripts = {};
+    if (!pkg.scripts['build:tokens']) {
+      pkg.scripts['build:tokens'] = 'node brand/build.js';
+      writeFile(
+        path.join(projectRoot, 'package.json'),
+        JSON.stringify(pkg, null, 2) + '\n'
+      );
+      console.log('   ✓ Added "build:tokens" script to package.json');
+    } else {
+      console.log('   ⏭ "build:tokens" script already exists in package.json');
+    }
+  }
+
+  // --- Summary ---
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('Brand setup complete!\n');
+  console.log('Next steps:');
+  console.log('1. Edit your brand tokens in brand/');
+  console.log('   - fonts.json  → Font families and weights');
+  console.log('   - light.json  → Light theme colors (neutral, accent, brand, state)');
+  console.log('   - dark.json   → Dark theme colors');
+  console.log('');
+  console.log('2. Build your brand CSS:');
+  console.log('   npm run build:tokens');
+  console.log('');
+  console.log(`3. Link the generated CSS in your HTML:`);
+  console.log(`   <link rel="stylesheet" href="/styles/tokens-${brandName}-light.css" />`);
+  console.log('');
+  console.log('Token reference guide:');
+  console.log('  Colors use T1 primitives like {color.gray.9}, {color.indigo.11}');
+  console.log('  Available palettes: gray, mauve, sand, indigo, iris, mint, jade,');
+  console.log('  tomato, red, amber, green, blue, and more.');
+  console.log('  See node_modules/muka-ui/tokens/t1-primitives/color.json for all values.');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+}
+
+module.exports = brand;

package/cli/commands/components.js

@@ -0,0 +1,90 @@
+/**
+ * `muka-ui components` command
+ *
+ * Lists all available Muka UI components from the manifest.
+ */
+
+const manifest = require('../manifest.json');
+
+/**
+ * Format a component for display
+ */
+function formatComponent(component, verbose = false) {
+  const lines = [];
+
+  // Component name and description
+  lines.push(`  ${component.name}`);
+  lines.push(`    ${component.description}`);
+
+  if (verbose) {
+    // Variants
+    if (component.variants && component.variants.length > 0) {
+      lines.push(`    Variants: ${component.variants.join(', ')}`);
+    }
+
+    // Sizes
+    if (component.sizes && component.sizes.length > 0) {
+      lines.push(`    Sizes: ${component.sizes.join(', ')}`);
+    }
+
+    // Props
+    if (component.props && component.props.length > 0) {
+      lines.push(`    Props: ${component.props.join(', ')}`);
+    }
+
+    // Subcomponents
+    if (component.subcomponents && component.subcomponents.length > 0) {
+      lines.push(`    Includes: ${component.subcomponents.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Main components command
+ */
+async function components(args) {
+  const verbose = args.includes('-v') || args.includes('--verbose');
+  const showPlanned = args.includes('-p') || args.includes('--planned');
+
+  console.log('\n🎨 Muka UI Components\n');
+
+  // Available components
+  console.log('Available:');
+  console.log('─────────────────────────────────────────────');
+
+  for (const component of manifest.components) {
+    console.log(formatComponent(component, verbose));
+    console.log('');
+  }
+
+  // Planned components
+  if (showPlanned) {
+    console.log('Planned (not yet available):');
+    console.log('─────────────────────────────────────────────');
+
+    for (const component of manifest.planned_components) {
+      console.log(`  ${component.name} (${component.roadmap})`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  console.log('─────────────────────────────────────────────');
+  console.log(`Total: ${manifest.components.length} available`);
+  if (!showPlanned) {
+    console.log(`       ${manifest.planned_components.length} planned (use --planned to show)`);
+  }
+  console.log('');
+  console.log(`Storybook: ${manifest.storybook_url}`);
+  console.log('');
+
+  // Usage hint
+  if (!verbose) {
+    console.log('Tip: Use --verbose (-v) for detailed props and variants');
+  }
+  console.log('');
+}
+
+module.exports = components;

package/cli/commands/init.js

@@ -0,0 +1,167 @@
+/**
+ * `muka-ui init` command
+ *
+ * Sets up a project for Muka UI usage:
+ * - Creates CLAUDE.md with AI development guidelines
+ * - Creates docs/muka-ui-guidelines.md with usage documentation
+ * - Checks for conflicting dependencies and warns
+ */
+
+const path = require('path');
+const {
+  fileExists,
+  ensureDir,
+  loadTemplate,
+  writeFile,
+  confirm,
+  findProjectRoot,
+  readPackageJson
+} = require('../lib/fs-utils');
+const { detectConflicts, printConflicts } = require('../lib/detect-conflicts');
+const manifest = require('../manifest.json');
+
+/**
+ * Generate component list for templates
+ */
+function generateComponentList() {
+  const lines = manifest.components.map(c => {
+    const variants = c.variants ? ` — ${c.variants.join(', ')}` : '';
+    return `- \`${c.name}\`${variants}: ${c.description}`;
+  });
+  return lines.join('\n');
+}
+
+/**
+ * Generate component table for guidelines
+ */
+function generateComponentTable() {
+  const header = '| Component | Description | Key Props |';
+  const separator = '|-----------|-------------|-----------|';
+  const rows = manifest.components.map(c => {
+    const props = c.props ? c.props.slice(0, 3).join(', ') + (c.props.length > 3 ? '...' : '') : '';
+    return `| \`${c.name}\` | ${c.description} | ${props} |`;
+  });
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Generate planned component table
+ */
+function generatePlannedComponentTable() {
+  const header = '| Component | Roadmap |';
+  const separator = '|-----------|---------|';
+  const rows = manifest.planned_components.map(c => {
+    return `| ${c.name} | ${c.roadmap} |`;
+  });
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Get template replacements
+ */
+function getReplacements() {
+  const pkg = require('../../package.json');
+  return {
+    STORYBOOK_URL: manifest.storybook_url,
+    PACKAGE_NAME: manifest.package_name,
+    VERSION: pkg.version,
+    DATE: new Date().toISOString().split('T')[0],
+    COMPONENT_LIST: generateComponentList(),
+    COMPONENT_TABLE: generateComponentTable(),
+    PLANNED_COMPONENT_TABLE: generatePlannedComponentTable()
+  };
+}
+
+/**
+ * Main init command
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function init(args) {
+  console.log('\n🎨 Muka UI Project Setup\n');
+
+  // Find project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Could not find package.json. Are you in a Node.js project?');
+  }
+
+  console.log(`Project: ${projectRoot}\n`);
+
+  // Check for conflicting dependencies
+  console.log('Checking dependencies...');
+  const conflicts = detectConflicts(projectRoot);
+  printConflicts(conflicts);
+
+  // Get template replacements
+  const replacements = getReplacements();
+
+  // --- CLAUDE.md ---
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  let createClaudeMd = true;
+
+  if (fileExists(claudeMdPath)) {
+    console.log('CLAUDE.md already exists.');
+    createClaudeMd = await confirm('Overwrite with Muka UI template?');
+  }
+
+  if (createClaudeMd) {
+    const claudeContent = loadTemplate('CLAUDE.md', replacements);
+    writeFile(claudeMdPath, claudeContent);
+    console.log('✓ Created CLAUDE.md\n');
+  } else {
+    console.log('⏭ Skipped CLAUDE.md\n');
+  }
+
+  // --- docs/muka-ui-guidelines.md ---
+  const docsDir = path.join(projectRoot, 'docs');
+  const guidelinesPath = path.join(docsDir, 'muka-ui-guidelines.md');
+
+  ensureDir(docsDir);
+
+  let createGuidelines = true;
+  if (fileExists(guidelinesPath)) {
+    console.log('docs/muka-ui-guidelines.md already exists.');
+    createGuidelines = await confirm('Overwrite with latest guidelines?');
+  }
+
+  if (createGuidelines) {
+    const guidelinesContent = loadTemplate('muka-ui-guidelines.md', replacements);
+    writeFile(guidelinesPath, guidelinesContent);
+    console.log('✓ Created docs/muka-ui-guidelines.md\n');
+  } else {
+    console.log('⏭ Skipped docs/muka-ui-guidelines.md\n');
+  }
+
+  // --- Check if muka-ui is installed ---
+  const projectPkg = readPackageJson(projectRoot);
+  const hasMukaUi = projectPkg?.dependencies?.['@revikornmann/muka-ui'] ||
+                    projectPkg?.devDependencies?.['@revikornmann/muka-ui'];
+
+  if (!hasMukaUi) {
+    console.log('⚠️  @revikornmann/muka-ui is not installed in this project.\n');
+    console.log('   Muka UI is a public npm package — no registry config needed:');
+    console.log('     npm install @revikornmann/muka-ui');
+    console.log('   For local development: npx muka-ui link /path/to/muka\n');
+  }
+
+  // --- Summary ---
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('Setup complete!\n');
+  console.log('Next steps:');
+  console.log('1. Import styles in your app root:');
+  console.log(`   import '${manifest.package_name}/styles';`);
+  console.log('');
+  console.log('2. Import components:');
+  console.log(`   import { Button, Card } from '${manifest.package_name}';`);
+  console.log('');
+  console.log(`3. Browse components: ${manifest.storybook_url}`);
+  console.log('');
+  console.log('4. Stay current: run `npx muka-ui install-skill` then `/setup-muka`');
+  console.log('   in Claude Code — it adds the auto-update workflow and registers');
+  console.log('   this repo as a consumer. (Or copy templates/update-muka.yml into');
+  console.log('   .github/workflows/ by hand.)');
+  console.log(`   See node_modules/${manifest.package_name}/docs/consumers/setup-instructions.md`);
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+}
+
+module.exports = init;

package/cli/commands/install-skill.js

@@ -0,0 +1,115 @@
+/**
+ * `muka-ui install-skill` command
+ *
+ * Copies the consumer-facing skills shipped inside the package (under
+ * `skills/`) into the consuming repo's `.claude/skills/` so Claude Code can
+ * discover them — most importantly `/setup-muka`.
+ *
+ * Claude Code only discovers skills under `.claude/skills/`, never inside
+ * `node_modules/`, so a skill shipped in the package is present but not
+ * discoverable until it is copied in. This command is that bridge.
+ *
+ *   npx muka-ui install-skill            # install all shipped skills
+ *   npx muka-ui install-skill setup-muka # install a specific skill
+ */
+
+const path = require('path');
+const fs = require('fs');
+const {
+  fileExists,
+  dirExists,
+  ensureDir,
+  readFile,
+  writeFile,
+  confirm,
+  findProjectRoot
+} = require('../lib/fs-utils');
+
+// Package root = two levels up from cli/commands.
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const SHIPPED_SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
+
+/**
+ * List the skill names shipped in the package.
+ */
+function listShippedSkills() {
+  if (!dirExists(SHIPPED_SKILLS_DIR)) {
+    return [];
+  }
+  return fs
+    .readdirSync(SHIPPED_SKILLS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fileExists(path.join(SHIPPED_SKILLS_DIR, d.name, 'SKILL.md')))
+    .map((d) => d.name);
+}
+
+/**
+ * Copy one shipped skill into the project's .claude/skills directory.
+ * Returns true if written, false if skipped.
+ */
+async function installOne(skillName, projectRoot) {
+  const src = path.join(SHIPPED_SKILLS_DIR, skillName, 'SKILL.md');
+  if (!fileExists(src)) {
+    console.log(`⚠️  No shipped skill named "${skillName}".`);
+    return false;
+  }
+
+  const destDir = path.join(projectRoot, '.claude', 'skills', skillName);
+  const dest = path.join(destDir, 'SKILL.md');
+
+  if (fileExists(dest)) {
+    if (readFile(dest) === readFile(src)) {
+      console.log(`✓ /${skillName} already up to date`);
+      return false;
+    }
+    const overwrite = await confirm(`/${skillName} already exists. Overwrite?`);
+    if (!overwrite) {
+      console.log(`⏭ Skipped /${skillName}`);
+      return false;
+    }
+  }
+
+  ensureDir(destDir);
+  writeFile(dest, readFile(src));
+  console.log(`✓ Installed /${skillName} → .claude/skills/${skillName}/SKILL.md`);
+  return true;
+}
+
+async function installSkill(args) {
+  console.log('\n🎨 Muka UI — install skills\n');
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Could not find package.json. Are you in a Node.js project?');
+  }
+
+  const available = listShippedSkills();
+  if (available.length === 0) {
+    throw new Error(
+      `No shipped skills found at ${SHIPPED_SKILLS_DIR}. ` +
+        'Is @revikornmann/muka-ui installed?'
+    );
+  }
+
+  const requested = args && args.length > 0 ? args : available;
+  let installed = 0;
+  for (const name of requested) {
+    if (!available.includes(name)) {
+      console.log(`⚠️  "${name}" is not a shipped skill (available: ${available.join(', ')})`);
+      continue;
+    }
+    if (await installOne(name, projectRoot)) {
+      installed += 1;
+    }
+  }
+
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  if (installed > 0) {
+    console.log('Done. Restart Claude Code if it is open, then run:');
+    console.log('   /setup-muka [brand]');
+  } else {
+    console.log('Nothing to install — skills already present.');
+  }
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+}
+
+module.exports = installSkill;