create-semaphor-app 0.1.3 → 0.1.5

package/README.md

@@ -7,8 +7,9 @@ npx create-semaphor-app@latest
 ```
 
 The CLI scaffolds the public Semaphor Data App Starter, installs local
-dependencies by default, and can optionally install the Semaphor Agent Plugin
-for detected Codex and Claude Code installations.
+dependencies by default, installs the production Semaphor shadcn registry
+components, and can optionally install the Semaphor Agent Plugin for detected
+Codex and Claude Code installations.
 
 It does not authenticate to Semaphor, write tokens, or choose a project/domain.
 The Semaphor Agent Plugin handles OAuth, project selection, runtime token
@@ -25,17 +26,63 @@ When `app-name` is omitted, the CLI creates `./semaphor-data-app`.
 Options:
 
 ```text
---no-install              Skip dependency installation.
+--no-install              Skip dependency installation. Requires --components none.
 --package-manager <name>  Use npm, pnpm, yarn, or bun. Defaults to detected npm.
 --skip-plugin             Skip Codex/Claude plugin install prompts.
 --install-codex-plugin    Install the Codex plugin without prompting.
 --install-claude-plugin   Install the Claude Code plugin without prompting.
 --template <source>       Starter source. Defaults to the public starter repo.
 --template-ref <ref>      Git branch/tag for the default starter repo. Defaults to main.
+--shadcn-preset <preset>  Apply a shadcn preset before adding Semaphor components.
+--shadcn-base <base>      Pass base or radix to shadcn init when using a preset.
+--components <list>       Add Semaphor registry components. Defaults to all. Use none, query, metrics,
+                          filters, card, table, matrix, recommended, all, or a comma-separated list.
 --yes                     Use noninteractive defaults; skip optional plugin installs unless explicit.
 --help                    Show help.
 ```
 
+## shadcn Presets And Semaphor Components
+
+The starter ships with a working shadcn setup. For teams that bring their own
+style, pass a shadcn preset during creation:
+
+```bash
+npx create-semaphor-app@latest my-app --shadcn-preset <preset-id>
+```
+
+Semaphor UI helpers are added from the public shadcn registry at scaffold time.
+By default, `create-semaphor-app` installs all production app-building
+components. Use `--components none` when you want the starter without Semaphor
+registry components:
+
+```bash
+npx create-semaphor-app@latest my-app
+npx create-semaphor-app@latest my-app --components none
+npx create-semaphor-app@latest my-app --components table
+npx create-semaphor-app@latest my-app --components query-state,view-card,metric-kpis,filter-controls,server-data-table,matrix-table
+```
+
+Component presets:
+
+| Value | Installs |
+| --- | --- |
+| `none` | No Semaphor registry components. |
+| `query` | `query-state` |
+| `metrics` | `query-state-boundary`, `metric-kpis` |
+| `filters` | `filter-controls` |
+| `card` | `view-card` |
+| `table` | `query-state`, `server-data-table` |
+| `matrix` | `query-state`, `matrix-table` |
+| `recommended` | `query-state`, `query-state-boundary`, `view-card`, `metric-kpis`, `filter-controls`, `server-data-table` |
+| `all` | `query-state`, `query-state-boundary`, `view-card`, `metric-kpis`, `filter-controls`, `server-data-table`, `matrix-table`. This is the default. |
+
+Registry components install as source into the generated app. They are optional
+UI accelerators and do not replace `react-semaphor/data-app-sdk`.
+
+`--shadcn-preset` and installed registry components run the shadcn CLI. To skip
+installs, pass `--no-install --components none`, then run the shadcn commands
+manually later if needed.
+
 ## Local Validation
 
 ```bash

package/bin/create-semaphor-app.mjs

@@ -13,6 +13,47 @@ const DEFAULT_TEMPLATE_REF = 'main';
 const DEFAULT_APP_NAME = 'semaphor-data-app';
 const MARKETPLACE = 'semaphor-analytics/agent-plugin';
 const PLUGIN_ID = 'semaphor@semaphor-analytics';
+const SEMAPHOR_COMPONENT_REGISTRY = 'semaphor-analytics/semaphor-data-app-components';
+const SEMAPHOR_COMPONENT_PRESETS = Object.freeze({
+  none: [],
+  query: ['query-state'],
+  table: ['query-state', 'server-data-table'],
+  metrics: ['query-state-boundary', 'metric-kpis'],
+  filters: ['filter-controls'],
+  card: ['view-card'],
+  matrix: ['query-state', 'matrix-table'],
+  recommended: [
+    'query-state',
+    'query-state-boundary',
+    'view-card',
+    'metric-kpis',
+    'filter-controls',
+    'server-data-table',
+  ],
+  all: [
+    'query-state',
+    'query-state-boundary',
+    'view-card',
+    'metric-kpis',
+    'filter-controls',
+    'server-data-table',
+    'matrix-table',
+  ],
+});
+const SEMAPHOR_COMPONENT_ALIASES = Object.freeze({
+  'query-state': 'query-state',
+  'query-state-boundary': 'query-state-boundary',
+  'view-card': 'view-card',
+  card: 'view-card',
+  'server-data-table': 'server-data-table',
+  table: 'server-data-table',
+  'metric-kpis': 'metric-kpis',
+  kpis: 'metric-kpis',
+  'filter-controls': 'filter-controls',
+  filters: 'filter-controls',
+  'matrix-table': 'matrix-table',
+  matrix: 'matrix-table',
+});
 const canPrompt = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
 const cwd = process.cwd();
@@ -24,13 +65,17 @@ Usage:
   npx create-semaphor-app@latest [app-name] [options]
 
 Options:
-  --no-install              Skip dependency installation.
+  --no-install              Skip dependency installation. Requires --components none.
   --package-manager <name>  Use npm, pnpm, yarn, or bun.
   --skip-plugin             Skip Codex/Claude plugin install prompts.
   --install-codex-plugin    Install the Codex plugin without prompting.
   --install-claude-plugin   Install the Claude Code plugin without prompting.
   --template <source>       Starter source. Can be a local directory or git URL.
   --template-ref <ref>      Git branch/tag for the default starter repo.
+  --shadcn-preset <preset>  Apply a shadcn preset before adding Semaphor components.
+  --shadcn-base <base>      Pass base or radix to shadcn init when using a preset.
+  --components <list>       Add Semaphor registry components. Defaults to all. Use none, query, metrics,
+                            filters, card, table, matrix, recommended, all, or a comma-separated list.
   --yes, -y                 Use noninteractive defaults; skip optional plugin installs unless explicit.
   --help, -h                Show this help.
 `;
@@ -46,6 +91,9 @@ function parseArgs(argv) {
     installClaudePlugin: false,
     template: DEFAULT_TEMPLATE_REPO,
     templateRef: DEFAULT_TEMPLATE_REF,
+    shadcnPreset: null,
+    shadcnBase: null,
+    components: 'all',
     yes: false,
     help: false,
   };
@@ -74,6 +122,18 @@ function parseArgs(argv) {
       parsed.templateRef = readRequiredValue(argv, ++i, arg);
     } else if (arg.startsWith('--template-ref=')) {
       parsed.templateRef = arg.slice('--template-ref='.length);
+    } else if (arg === '--shadcn-preset') {
+      parsed.shadcnPreset = readRequiredValue(argv, ++i, arg);
+    } else if (arg.startsWith('--shadcn-preset=')) {
+      parsed.shadcnPreset = arg.slice('--shadcn-preset='.length);
+    } else if (arg === '--shadcn-base') {
+      parsed.shadcnBase = readRequiredValue(argv, ++i, arg);
+    } else if (arg.startsWith('--shadcn-base=')) {
+      parsed.shadcnBase = arg.slice('--shadcn-base='.length);
+    } else if (arg === '--components') {
+      parsed.components = readRequiredValue(argv, ++i, arg);
+    } else if (arg.startsWith('--components=')) {
+      parsed.components = arg.slice('--components='.length);
     } else if (arg === '--yes' || arg === '-y') {
       parsed.yes = true;
     } else if (arg.startsWith('-')) {
@@ -225,6 +285,23 @@ function resolvePackageManager(requested) {
   return 'npm';
 }
 
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function resolveShadcnRunner(packageManager) {
+  if (packageManager === 'pnpm') {
+    return { command: 'pnpm', args: ['dlx', 'shadcn@latest'] };
+  }
+  if (packageManager === 'yarn') {
+    return { command: 'yarn', args: ['dlx', 'shadcn@latest'] };
+  }
+  if (packageManager === 'bun') {
+    return { command: 'bunx', args: ['--bun', 'shadcn@latest'] };
+  }
+  return { command: 'npx', args: ['shadcn@latest'] };
+}
+
 function installArgs(packageManager) {
   if (packageManager === 'yarn') return [];
   return ['install'];
@@ -315,6 +392,107 @@ function loadTemplate(template, templateRef) {
   return { tempRoot, templateDir };
 }
 
+function normalizeSemaphorComponents(value) {
+  const raw = String(value || 'none')
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean);
+  if (raw.length === 0) return [];
+
+  const components = [];
+  for (const entry of raw) {
+    if (hasOwn(SEMAPHOR_COMPONENT_PRESETS, entry)) {
+      components.push(...SEMAPHOR_COMPONENT_PRESETS[entry]);
+      continue;
+    }
+    if (!hasOwn(SEMAPHOR_COMPONENT_ALIASES, entry)) {
+      throw new Error(
+        `Unsupported Semaphor component "${entry}". Use none, query, metrics, filters, card, table, matrix, recommended, all, or one of ${Object.keys(SEMAPHOR_COMPONENT_ALIASES).join(', ')}.`,
+      );
+    }
+    components.push(SEMAPHOR_COMPONENT_ALIASES[entry]);
+  }
+
+  return Array.from(new Set(components));
+}
+
+function normalizeShadcnBase(value) {
+  if (!value) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (!['base', 'radix'].includes(normalized)) {
+    throw new Error('--shadcn-base must be base or radix.');
+  }
+  return normalized;
+}
+
+function validateScaffoldOptions(args) {
+  const components = normalizeSemaphorComponents(args.components);
+  normalizeShadcnBase(args.shadcnBase);
+
+  if (args.shadcnBase && !args.shadcnPreset) {
+    throw new Error('--shadcn-base requires --shadcn-preset.');
+  }
+
+  if (args.shadcnPreset !== null && String(args.shadcnPreset).trim() === '') {
+    throw new Error('--shadcn-preset requires a non-empty preset id.');
+  }
+
+  if (!args.install && (args.shadcnPreset || components.length > 0)) {
+    throw new Error(
+      '--no-install cannot be combined with --shadcn-preset or --components. Run create-semaphor-app with installs enabled, or add shadcn components manually after scaffolding.',
+    );
+  }
+}
+
+function runShadcn(packageManager, targetDir, args) {
+  const runner = resolveShadcnRunner(packageManager);
+  ensureCommand(runner.command, runner.command);
+  runRequired(runner.command, [...runner.args, ...args], {
+    cwd: targetDir,
+    stdio: 'inherit',
+  });
+}
+
+function customizeShadcn(args, packageManager, targetDir) {
+  const components = normalizeSemaphorComponents(args.components);
+  const shadcnBase = normalizeShadcnBase(args.shadcnBase);
+
+  if (!args.shadcnPreset && components.length === 0) {
+    return { presetApplied: false, components };
+  }
+
+  if (args.shadcnPreset) {
+    const initArgs = [
+      'init',
+      '--preset',
+      args.shadcnPreset,
+      '--template',
+      'vite',
+      '--force',
+      '--reinstall',
+    ];
+    if (shadcnBase) {
+      initArgs.push('--base', shadcnBase);
+    }
+    console.log(`\nApplying shadcn preset ${args.shadcnPreset}...`);
+    runShadcn(packageManager, targetDir, initArgs);
+    console.log('✓ Applied shadcn preset');
+  }
+
+  if (components.length > 0) {
+    console.log('\nAdding Semaphor registry components...');
+    for (const component of components) {
+      runShadcn(packageManager, targetDir, [
+        'add',
+        `${SEMAPHOR_COMPONENT_REGISTRY}/${component}`,
+      ]);
+      console.log(`✓ Added ${component}`);
+    }
+  }
+
+  return { presetApplied: Boolean(args.shadcnPreset), components };
+}
+
 function detectAgents() {
   return {
     codex: commandExists('codex'),
@@ -411,12 +589,22 @@ async function maybeInstallPlugins(args, rl) {
   return { detected, results, skipped: false };
 }
 
-function printNextSteps({ targetDir, packageManager, pluginSummary }) {
+function printNextSteps({ targetDir, packageManager, pluginSummary, shadcnSummary }) {
   const relativeTarget = path.relative(cwd, targetDir) || '.';
   console.log('\nNext:');
   console.log(`  cd ${relativeTarget}`);
   console.log(`  ${packageManager} run dev`);
 
+  if (shadcnSummary?.presetApplied || shadcnSummary?.components?.length > 0) {
+    console.log('\nConfigured shadcn:');
+    if (shadcnSummary.presetApplied) {
+      console.log('  - Applied custom preset');
+    }
+    for (const component of shadcnSummary.components ?? []) {
+      console.log(`  - Added Semaphor ${component}`);
+    }
+  }
+
   if (pluginSummary?.skipped) {
     printPluginInstructions();
     printBuildPrompt();
@@ -487,6 +675,14 @@ async function main() {
     console.log(usage());
     return;
   }
+  try {
+    validateScaffoldOptions(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error('');
+    console.error(usage());
+    process.exit(1);
+  }
 
   const rl = readline.createInterface({
     input: process.stdin,
@@ -520,11 +716,13 @@ async function main() {
       console.log('Skipping dependency installation.');
     }
 
+    const shadcnSummary = customizeShadcn(args, packageManager, target.targetDir);
     const pluginSummary = await maybeInstallPlugins(args, rl);
     printNextSteps({
       targetDir: target.targetDir,
       packageManager,
       pluginSummary,
+      shadcnSummary,
     });
   } catch (error) {
     console.error('\nUnable to create Semaphor app.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-semaphor-app",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Create a Semaphor Data App starter project.",
   "type": "module",
   "bin": {

package/scripts/smoke-test.mjs

@@ -98,6 +98,8 @@ async function main() {
         '--template',
         defaultLocalStarterPath,
         '--no-install',
+        '--components',
+        'none',
         '--skip-plugin',
         '--yes',
       ], { cwd: root });
@@ -113,6 +115,8 @@ async function main() {
         '--template',
         defaultLocalStarterPath,
         '--no-install',
+        '--components',
+        'none',
         '--skip-plugin',
         '--yes',
       ], { cwd: root });
@@ -126,6 +130,8 @@ async function main() {
       const result = runCli([
         'github-template-app',
         '--no-install',
+        '--components',
+        'none',
         '--skip-plugin',
         '--yes',
       ], { cwd: root });
@@ -146,6 +152,8 @@ async function main() {
         '--template',
         defaultLocalStarterPath,
         '--no-install',
+        '--components',
+        'none',
         '--install-codex-plugin',
       ], {
         cwd: root,
@@ -168,6 +176,146 @@ async function main() {
       console.log('✓ fake Codex plugin install path');
     }
 
+    {
+      const root = createTempRoot('default-components-');
+      const binDir = path.join(root, 'bin');
+      fs.mkdirSync(binDir, { recursive: true });
+      const shadcnLog = path.join(root, 'shadcn.log');
+      const npmLog = path.join(root, 'npm.log');
+      createFakeCommand(binDir, 'npx', shadcnLog);
+      createFakeCommand(binDir, 'npm', npmLog);
+
+      const result = runCli([
+        'default-components-app',
+        '--template',
+        defaultLocalStarterPath,
+        '--skip-plugin',
+        '--yes',
+        '--package-manager',
+        'npm',
+      ], {
+        cwd: root,
+        env: {
+          ...process.env,
+          PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`,
+        },
+      });
+      assertSuccess(result, 'default component install');
+      assertScaffold(root, 'default-components-app');
+      const npmInstallLog = fs.readFileSync(npmLog, 'utf8');
+      assert(npmInstallLog.includes('npm install'), 'expected npm install command');
+      const log = fs.readFileSync(shadcnLog, 'utf8');
+      for (const component of [
+        'query-state',
+        'query-state-boundary',
+        'view-card',
+        'metric-kpis',
+        'filter-controls',
+        'server-data-table',
+        'matrix-table',
+      ]) {
+        assert(
+          log.includes(`npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/${component}`),
+          `expected default ${component} registry add command`,
+        );
+      }
+      console.log('✓ default Semaphor registry component install');
+    }
+
+    {
+      const root = createTempRoot('shadcn-');
+      const binDir = path.join(root, 'bin');
+      fs.mkdirSync(binDir, { recursive: true });
+      const shadcnLog = path.join(root, 'shadcn.log');
+      const npmLog = path.join(root, 'npm.log');
+      createFakeCommand(binDir, 'npx', shadcnLog);
+      createFakeCommand(binDir, 'npm', npmLog);
+
+      const result = runCli([
+        'styled-app',
+        '--template',
+        defaultLocalStarterPath,
+        '--skip-plugin',
+        '--yes',
+        '--package-manager',
+        'npm',
+        '--shadcn-preset',
+        'test-preset',
+        '--shadcn-base',
+        'base',
+        '--components',
+        'recommended,matrix-table',
+      ], {
+        cwd: root,
+        env: {
+          ...process.env,
+          PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`,
+        },
+      });
+      assertSuccess(result, 'shadcn preset and component install');
+      assertScaffold(root, 'styled-app');
+      const npmInstallLog = fs.readFileSync(npmLog, 'utf8');
+      assert(npmInstallLog.includes('npm install'), 'expected npm install command');
+      const log = fs.readFileSync(shadcnLog, 'utf8');
+      assert(
+        log.includes('npx shadcn@latest init --preset test-preset --template vite --force --reinstall --base base'),
+        'expected shadcn preset init command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/query-state'),
+        'expected query-state registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/query-state-boundary'),
+        'expected query-state-boundary registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/view-card'),
+        'expected view-card registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/metric-kpis'),
+        'expected metric-kpis registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/filter-controls'),
+        'expected filter-controls registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/server-data-table'),
+        'expected server-data-table registry add command',
+      );
+      assert(
+        log.includes('npx shadcn@latest add semaphor-analytics/semaphor-data-app-components/matrix-table'),
+        'expected matrix-table registry add command',
+      );
+      console.log('✓ shadcn preset and registry component path');
+    }
+
+    {
+      const root = createTempRoot('no-install-shadcn-');
+      const result = runCli([
+        'invalid-shadcn-app',
+        '--template',
+        defaultLocalStarterPath,
+        '--no-install',
+        '--skip-plugin',
+        '--yes',
+        '--components',
+        'table',
+      ], { cwd: root });
+      assert(result.status !== 0, 'expected shadcn options with --no-install to fail');
+      assert(
+        result.stderr.includes('--no-install cannot be combined'),
+        'expected actionable --no-install error',
+      );
+      assert(
+        !fs.existsSync(path.join(root, 'invalid-shadcn-app')),
+        'invalid shadcn options should fail before scaffolding',
+      );
+      console.log('✓ rejects shadcn customization with --no-install');
+    }
+
     console.log('✓ cleaned up temp projects');
   } finally {
     for (const root of tempRoots.reverse()) {