@archetypeai/ds-cli 0.3.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archetype AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+## @archetypeai/ds-cli
+
+`@archetypeai/ds-cli` is the CLI for the **Archetype AI Design System**. It provides commands for creating, configuring, and managing projects that use the design system.
+
+---
+
+## Commands
+
+### `create` — Scaffold a new project
+
+```bash
+npx @archetypeai/ds-cli create my-app
+```
+
+Scaffolds a full SvelteKit + Tailwind v4 + shadcn-svelte project:
+
+1. Creates a SvelteKit project via `sv create`
+2. Installs design tokens (`@archetypeai/ds-lib-tokens`)
+3. Optionally installs internal fonts (`@archetypeai/ds-lib-fonts-internal`)
+4. Initializes shadcn-svelte (`components.json`, `utils.js`, dependencies)
+5. Configures CSS (`layout.css` with design tokens and optional fonts import)
+6. Installs all components from the design system registry
+7. Optionally installs AI agent configuration (Cursor or Claude Code)
+8. Creates a demo page with Button examples
+
+#### Create flags
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--framework` | `svelte` | prompt |
+| `--pm` | `npm`, `pnpm`, `bun`, `yarn` | prompt |
+| `--fonts` / `--no-fonts` | boolean | prompt (default: yes) |
+| `--no-components` | skip component installation | install all |
+| `--codeagent` | `cursor`, `claude`, `none` | prompt |
+
+```bash
+npx @archetypeai/ds-cli create my-app --framework svelte --pm pnpm --no-fonts --codeagent none
+```
+
+---
+
+### `init` — Add DS to an existing project
+
+```bash
+cd my-existing-app
+npx @archetypeai/ds-cli init
+```
+
+Run from an existing SvelteKit project root. Detects your package manager from the lockfile and installs the design system without creating a new project:
+
+1. Detects project (verifies `package.json` and `svelte.config.js`)
+2. Auto-detects package manager from lockfile
+3. Installs Tailwind CSS v4 if not already present
+4. Installs design tokens
+5. Optionally installs internal fonts
+6. Initializes shadcn-svelte
+7. Prepends DS imports to existing `layout.css` (preserves your styles)
+8. Installs all components from the registry
+9. Optionally installs AI agent configuration
+
+#### Init flags
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--pm` | `npm`, `pnpm`, `bun`, `yarn` | auto-detect from lockfile |
+| `--fonts` / `--no-fonts` | boolean | prompt (default: yes) |
+| `--no-components` | skip component installation | install all |
+| `--codeagent` | `cursor`, `claude`, `none` | prompt |
+
+```bash
+npx @archetypeai/ds-cli init --pm npm --no-fonts --codeagent none
+```
+
+---
+
+### `add` — Add components or agent configurations
+
+#### `add ds-ui-svelte` — Install all design system components
+
+```bash
+npx @archetypeai/ds-cli add ds-ui-svelte
+```
+
+Installs all components from the design system registry into your project. Requires shadcn-svelte to be initialized (`components.json` must exist).
+
+#### `add ds-config-codeagent` — Install agent configuration
+
+```bash
+npx @archetypeai/ds-cli add ds-config-codeagent --cursor
+npx @archetypeai/ds-cli add ds-config-codeagent --claude
+```
+
+Installs agent configuration files (AGENTS.md/CLAUDE.md, skills, and rules) for the specified IDE. If no flag is provided, an interactive prompt will ask which IDE to configure.
+
+| Flag | Effect |
+|------|--------|
+| `--cursor` | Copies AGENTS.md, skills, and rules to `.cursor/` |
+| `--claude` | Copies CLAUDE.md, skills, and rules to `.claude/` |
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REGISTRY_URL` | `https://design-system.archetypeai.workers.dev` | Override the component registry URL for testing or private registries |
+
+---
+
+## Security
+
+The CLI validates all data from external sources before use:
+
+- **Registry URLs** are validated against an HTTPS + `/r/<name>.json` pattern before being passed to any shell command
+- **Shell commands** use `execFileSync` (no shell interpolation) to prevent injection even if validation is bypassed
+- **Package manager** and **framework** flag values are validated against known allowlists
+- **Fetch requests** have a 15-second timeout to prevent hanging on unresponsive registries
+
+---
+
+## Fonts
+
+The internal fonts package (`@archetypeai/ds-lib-fonts-internal`) is not yet published. When available, it will be on npmjs.org. If omitted, the theme falls back to system fonts.

package/bin.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { create } from './commands/create.js';
+import { init } from './commands/init.js';
+import { add } from './commands/add.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
+  return pkg.version;
+}
+
+function printUsage() {
+  console.log(`
+ds - Archetype AI Design System CLI
+
+Usage:
+  npx @archetypeai/ds-cli create [project-name] [flags]        Create a new project
+  npx @archetypeai/ds-cli init [flags]                          Init DS in existing project
+  npx @archetypeai/ds-cli add <target> [flags]                  Add components or configs
+  npx @archetypeai/ds-cli --help                                Show this help message
+  npx @archetypeai/ds-cli --version                             Show version
+
+Create flags:
+  --framework <svelte>              Framework to use (default: prompt)
+  --pm <npm|pnpm|bun|yarn>          Package manager (default: prompt)
+  --fonts / --no-fonts              Install internal fonts (default: prompt)
+  --no-components                   Skip component installation (default: install all)
+  --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
+
+Init flags:
+  --pm <npm|pnpm|bun|yarn>          Package manager (default: auto-detect)
+  --fonts / --no-fonts              Install internal fonts (default: prompt)
+  --no-components                   Skip component installation (default: install all)
+  --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
+
+Add targets:
+  ds-ui-svelte                      Install all design system components
+  ds-config-codeagent [flags]       Install agent configuration files
+    --cursor                        Setup for Cursor IDE
+    --claude                        Setup for Claude Code
+`);
+}
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+switch (command) {
+  case 'create':
+    await create(args);
+    break;
+  case 'init':
+    await init(args);
+    break;
+  case 'add':
+    await add(args);
+    break;
+  case '--help':
+  case '-h':
+    printUsage();
+    break;
+  case '--version':
+  case '-v':
+    console.log(getVersion());
+    break;
+  default:
+    if (command) {
+      console.error(`Unknown command: ${command}\n`);
+    }
+    printUsage();
+    if (command) process.exit(1);
+    break;
+}

package/commands/add.js

@@ -0,0 +1,42 @@
+import * as p from '@clack/prompts';
+import { addDsUiSvelte } from '../lib/add-ds-ui-svelte.js';
+import { addDsConfigCodeagent } from '../lib/add-ds-config-codeagent.js';
+
+const VALID_TARGETS = ['ds-ui-svelte', 'ds-config-codeagent'];
+
+function printUsage() {
+  console.log(`
+ds add - Add components or configurations
+
+Usage:
+  npx @archetypeai/ds-cli add ds-ui-svelte                     Install all design system components
+  npx @archetypeai/ds-cli add ds-config-codeagent [flags]      Install agent configuration
+    --cursor                                                Setup for Cursor IDE
+    --claude                                                Setup for Claude Code
+`);
+}
+
+export async function add(args) {
+  const target = args[0];
+  const flags = args.slice(1);
+
+  switch (target) {
+    case 'ds-ui-svelte':
+      await addDsUiSvelte(flags);
+      break;
+    case 'ds-config-codeagent':
+      await addDsConfigCodeagent(flags);
+      break;
+    case '--help':
+    case '-h':
+      printUsage();
+      break;
+    default:
+      if (target) {
+        p.log.error(`Unknown add target: "${target}". Valid targets: ${VALID_TARGETS.join(', ')}`);
+      }
+      printUsage();
+      if (target) process.exit(1);
+      break;
+  }
+}

package/commands/create.js

@@ -0,0 +1,238 @@
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import * as p from '@clack/prompts';
+import { getPm, pmNames, isPmInstalled } from '../lib/use-package-manager.js';
+import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
+import {
+  runSvCreate,
+  installTokens,
+  installFonts,
+  initShadcn,
+  configureCss,
+  installComponents,
+  createDemoPage,
+  installAgentConfig
+} from '../lib/scaffold-ds-svelte-project.js';
+
+// parse flags
+export function parseFlags(args) {
+  const flags = {
+    name: null,
+    framework: null,
+    pm: null,
+    fonts: null,
+    components: true,
+    agent: null
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--framework' && args[i + 1]) {
+      flags.framework = args[++i];
+    } else if (arg === '--pm' && args[i + 1]) {
+      flags.pm = args[++i];
+    } else if (arg === '--fonts') {
+      flags.fonts = true;
+    } else if (arg === '--no-fonts') {
+      flags.fonts = false;
+    } else if (arg === '--no-components') {
+      flags.components = false;
+    } else if (arg === '--codeagent' && args[i + 1]) {
+      flags.agent = args[++i];
+    } else if (!arg.startsWith('--') && !flags.name) {
+      flags.name = arg;
+    }
+  }
+
+  return flags;
+}
+
+// create a new project
+export async function create(args) {
+  const flags = parseFlags(args);
+
+  p.intro('Create a new project using Archetype AI Design System.');
+
+  // specify project name
+  let name = flags.name;
+  if (!name) {
+    name = await p.text({
+      message: 'What is your project name?',
+      placeholder: 'my-app',
+      validate(value) {
+        if (!value.trim()) return 'Project name is required.';
+        if (!/^[a-z0-9-]+$/.test(value.trim()))
+          return 'Use lowercase letters, numbers, and hyphens only.';
+      }
+    });
+    if (p.isCancel(name)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+  name = name.trim();
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    p.log.error('Invalid project name. Use lowercase letters, numbers, and hyphens only.');
+    process.exit(1);
+  }
+
+  // validate --pm flag
+  if (flags.pm && !pmNames.includes(flags.pm)) {
+    p.log.error(`Invalid --pm value "${flags.pm}". Must be one of: ${pmNames.join(', ')}`);
+    process.exit(1);
+  }
+
+  // validate --framework flag
+  if (flags.framework && flags.framework !== 'svelte') {
+    p.log.error(
+      `Unsupported framework "${flags.framework}". Currently only "svelte" is supported.`
+    );
+    process.exit(1);
+  }
+
+  // specify framework
+  let framework = flags.framework;
+  if (!framework) {
+    framework = await p.select({
+      message: 'Which framework?',
+      options: [{ value: 'svelte', label: 'SvelteKit', hint: 'Svelte 5 + Tailwind v4' }]
+    });
+    if (p.isCancel(framework)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  // specify package manager
+  let pmName = flags.pm;
+  if (!pmName) {
+    pmName = await p.select({
+      message: 'Which package manager?',
+      options: pmNames.map((n) => ({ value: n, label: n }))
+    });
+    if (p.isCancel(pmName)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+  const pm = getPm(pmName);
+
+  // verify package manager is installed
+  if (!isPmInstalled(pmName)) {
+    p.log.error(`${pmName} is not installed. Please install it first and try again.`);
+    process.exit(1);
+  }
+
+  // check if directory exists
+  const targetDir = process.cwd();
+  const projectPath = resolve(targetDir, name);
+
+  if (existsSync(projectPath)) {
+    const overwrite = await p.confirm({
+      message: `Directory "${name}" already exists. Continue anyway?`,
+      initialValue: false
+    });
+    if (p.isCancel(overwrite) || !overwrite) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  // create SvelteKit project
+  const created = runSvCreate(pm, name, targetDir);
+  if (!created) {
+    process.exit(1);
+  }
+
+  // specify fonts
+  let includeFonts = flags.fonts;
+  if (includeFonts === null) {
+    includeFonts = await p.confirm({
+      message: 'Install internal fonts package?',
+      initialValue: true
+    });
+    if (p.isCancel(includeFonts)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  // install packages
+  const tokensOk = installTokens(pm, projectPath);
+  if (!tokensOk) {
+    process.exit(1);
+  }
+
+  if (includeFonts) {
+    installFonts(pm, projectPath);
+  }
+
+  // init shadcn-svelte
+  initShadcn(pm, projectPath);
+
+  // configure CSS
+  configureCss(projectPath, includeFonts);
+
+  // install components
+  if (flags.components) {
+    try {
+      const s = p.spinner();
+      s.start('Fetching component list');
+      const components = await fetchComponents();
+      s.stop(`Found ${components.length} components`);
+      installComponents(pm, projectPath, components);
+    } catch (error) {
+      p.log.warn(`Component installation skipped: ${error.message}`);
+    }
+  } else {
+    p.log.info('Skipped component installation (--no-components)');
+  }
+
+  // specify agent config
+  let agent = flags.agent;
+  if (!agent) {
+    agent = await p.select({
+      message: 'Install AI agent configuration?',
+      options: [
+        { value: 'none', label: 'None' },
+        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
+        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules' }
+      ]
+    });
+    if (p.isCancel(agent)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  const validAgents = ['cursor', 'claude', 'none'];
+  if (!validAgents.includes(agent)) {
+    p.log.error(`Invalid --codeagent value "${agent}". Must be one of: ${validAgents.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (agent !== 'none') {
+    installAgentConfig(projectPath, agent);
+  }
+
+  // create demo page
+  createDemoPage(projectPath);
+
+  // summary
+  const summary = [
+    `Project:         ${name}`,
+    `Location:        ${projectPath}`,
+    `Framework:       ${framework}`,
+    `Package Manager: ${pm.name}`,
+    `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
+    `Components:      ${flags.components ? 'all' : 'skipped'}`,
+    `Agent Configuration:    ${agent}`
+  ].join('\n');
+
+  p.note(summary, 'Summary');
+
+  p.log.step(`cd ${name}`);
+  p.log.step(`${pm.name} run dev`);
+
+  p.outro('You are all set!');
+}

package/commands/init.js

@@ -0,0 +1,199 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import * as p from '@clack/prompts';
+import { getPm, pmNames, isPmInstalled, detectPm } from '../lib/use-package-manager.js';
+import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
+import {
+  installTailwind,
+  installTokens,
+  installFonts,
+  initShadcn,
+  prependCss,
+  installComponents,
+  installAgentConfig
+} from '../lib/scaffold-ds-svelte-project.js';
+
+// parse flags
+export function parseFlags(args) {
+  const flags = {
+    pm: null,
+    fonts: null,
+    components: true,
+    agent: null
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--pm' && args[i + 1]) {
+      flags.pm = args[++i];
+    } else if (arg === '--fonts') {
+      flags.fonts = true;
+    } else if (arg === '--no-fonts') {
+      flags.fonts = false;
+    } else if (arg === '--no-components') {
+      flags.components = false;
+    } else if (arg === '--codeagent' && args[i + 1]) {
+      flags.agent = args[++i];
+    }
+  }
+
+  return flags;
+}
+
+// check if project has Tailwind CSS
+function hasTailwind(projectPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf-8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return 'tailwindcss' in deps;
+  } catch {
+    return false;
+  }
+}
+
+// initialize the design system in an existing project
+export async function init(args) {
+  const flags = parseFlags(args);
+  const projectPath = process.cwd();
+
+  // validate --pm flag
+  if (flags.pm && !pmNames.includes(flags.pm)) {
+    p.log.error(`Invalid --pm value "${flags.pm}". Must be one of: ${pmNames.join(', ')}`);
+    process.exit(1);
+  }
+
+  p.intro('Initialize Archetype AI Design System in existing project.');
+
+  // detect project
+  if (!existsSync(join(projectPath, 'package.json'))) {
+    p.log.error('No package.json found. Run this command from your project root.');
+    process.exit(1);
+  }
+
+  const hasSvelteConfig =
+    existsSync(join(projectPath, 'svelte.config.js')) ||
+    existsSync(join(projectPath, 'svelte.config.mjs')) ||
+    existsSync(join(projectPath, 'svelte.config.ts'));
+  if (!hasSvelteConfig) {
+    p.log.warn('No svelte.config found. This command is designed for SvelteKit projects.');
+  }
+
+  // detect package manager
+  let pmName = flags.pm;
+  if (!pmName) {
+    pmName = detectPm(projectPath);
+    if (pmName) {
+      p.log.info(`Detected package manager: ${pmName}`);
+    }
+  }
+  if (!pmName) {
+    pmName = await p.select({
+      message: 'Which package manager?',
+      options: pmNames.map((n) => ({ value: n, label: n }))
+    });
+    if (p.isCancel(pmName)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+  const pm = getPm(pmName);
+
+  // verify package manager is installed
+  if (!isPmInstalled(pmName)) {
+    p.log.error(`${pmName} is not installed. Please install it first and try again.`);
+    process.exit(1);
+  }
+
+  // detect and install Tailwind if missing
+  if (!hasTailwind(projectPath)) {
+    p.log.info('Tailwind CSS not found in dependencies.');
+    const tailwindOk = installTailwind(pm, projectPath);
+    if (!tailwindOk) {
+      process.exit(1);
+    }
+  }
+
+  // specify fonts
+  let includeFonts = flags.fonts;
+  if (includeFonts === null) {
+    includeFonts = await p.confirm({
+      message: 'Install internal fonts package?',
+      initialValue: true
+    });
+    if (p.isCancel(includeFonts)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  // install packages
+  const tokensOk = installTokens(pm, projectPath);
+  if (!tokensOk) {
+    process.exit(1);
+  }
+
+  if (includeFonts) {
+    installFonts(pm, projectPath);
+  }
+
+  // init shadcn-svelte
+  initShadcn(pm, projectPath);
+
+  // configure CSS (prepend to existing)
+  prependCss(projectPath, includeFonts);
+
+  // install components
+  if (flags.components) {
+    try {
+      const s = p.spinner();
+      s.start('Fetching component list');
+      const components = await fetchComponents();
+      s.stop(`Found ${components.length} components`);
+      installComponents(pm, projectPath, components);
+    } catch (error) {
+      p.log.warn(`Component installation skipped: ${error.message}`);
+    }
+  } else {
+    p.log.info('Skipped component installation (--no-components)');
+  }
+
+  // specify agent config
+  let agent = flags.agent;
+  if (!agent) {
+    agent = await p.select({
+      message: 'Install AI agent configuration?',
+      options: [
+        { value: 'none', label: 'None' },
+        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
+        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules' }
+      ]
+    });
+    if (p.isCancel(agent)) {
+      p.cancel('Setup cancelled.');
+      process.exit(0);
+    }
+  }
+
+  const validAgents = ['cursor', 'claude', 'none'];
+  if (!validAgents.includes(agent)) {
+    p.log.error(`Invalid --codeagent value "${agent}". Must be one of: ${validAgents.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (agent !== 'none') {
+    installAgentConfig(projectPath, agent);
+  }
+
+  // summary
+  const summary = [
+    `Location:        ${projectPath}`,
+    `Package Manager: ${pm.name}`,
+    `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
+    `Components:      ${flags.components ? 'all' : 'skipped'}`,
+    `Agent Config:    ${agent}`
+  ].join('\n');
+
+  p.note(summary, 'Summary');
+
+  p.outro('You are all set!');
+}