create-auto-app 1.148.0 → 1.149.0

package/README.md

@@ -1,210 +1,226 @@
 # create-auto-app
 
-CLI scaffolding tool for creating new Auto Engineer applications.
-
----
+Create Auto Engineer apps with no configuration.
 
 ## Purpose
 
-This tool generates complete project structures with templates, dependencies, and configuration. It provides both interactive prompts and command-line options for quick project scaffolding.
-
----
+`create-auto-app` is a CLI scaffolding tool that generates complete Auto Engineer project structures. It copies a selected template, resolves the latest `@auto-engineer/*` package versions from npm, generates a unique project `fileId`, and optionally installs dependencies. It supports both interactive prompts and non-interactive flags.
 
 ## Installation
 
 ```bash
-# Global
+# Global install
 npm install -g create-auto-app
 
-# Or via npx
+# Or run directly with npx (no install needed)
 npx create-auto-app
 ```
 
+**Requires Node.js >= 18.0.0.**
+
 ## Quick Start
 
 ```bash
-# Step 1: Create a project
+# 1. Scaffold a new project (interactive mode)
+npx create-auto-app
+
+# 2. Or pass a project name directly (uses the "typical" template by default)
 npx create-auto-app my-app
 
-# Step 2: Navigate and install
+# 3. Enter the project directory
 cd my-app
-pnpm install
 
-# Step 3: Run
-pnpm dev
+# 4. Run Auto Engineer
+auto
 ```
 
----
+When run without arguments, the CLI prompts for:
+
+1. **Project name** (default: `my-auto-app`)
+2. **Template** (if multiple templates are available)
+3. **Install dependencies?** (default: yes)
 
 ## How-to Guides
 
-### Create with Template
+### Scaffold in the current directory
 
 ```bash
-create-auto-app my-shop --template=kanban-todo
+npx create-auto-app .
 ```
 
-### Create Minimal Project
+The project name is inferred from the current directory name.
 
-```bash
-create-auto-app my-app --preset=minimal
-```
-
-### Scaffold in Current Directory
+### Use a specific template
 
 ```bash
-create-auto-app . --preset=full
+npx create-auto-app my-app --template minimal
 ```
 
-### Use Specific Package Manager
+### Choose a package manager
+
+The CLI auto-detects your package manager (checks pnpm, then yarn, then falls back to npm). To override:
 
 ```bash
-create-auto-app my-app --use-pnpm
-create-auto-app my-app --use-yarn
-create-auto-app my-app --use-npm
+npx create-auto-app my-app --use-pnpm
+npx create-auto-app my-app --use-yarn
+npx create-auto-app my-app --use-npm
 ```
 
-### Skip Dependency Installation
+### Skip dependency installation
 
 ```bash
-create-auto-app my-app --no-install
+npx create-auto-app my-app --no-install
 ```
 
-### Configure for CI/CD
+### CI/CD usage
+
+Combine flags to avoid interactive prompts:
 
 ```bash
-create-auto-app my-app --preset=full --no-install --use-pnpm
+npx create-auto-app my-app --template typical --no-install --use-pnpm
 ```
 
----
+All required values are provided via flags, so no TTY is needed.
 
 ## CLI Reference
 
-### Commands
-
-#### `create-auto-app [project-name]`
-
-Create a new Auto Engineer project.
-
-```bash
+```
 create-auto-app [project-name] [options]
 ```
 
-| Option | Alias | Type | Default | Description |
-|--------|-------|------|---------|-------------|
-| `--template` | `-t` | string | - | Use a specific template |
-| `--preset` | `-p` | string | full | Package preset (minimal, full) |
-| `--no-install` | - | boolean | false | Skip dependency installation |
-| `--use-npm` | - | boolean | false | Force npm |
-| `--use-yarn` | - | boolean | false | Force yarn |
-| `--use-pnpm` | - | boolean | false | Force pnpm |
+If `project-name` is omitted, the CLI enters interactive mode.
 
-### Available Templates
+### Options
 
-| Template | Description |
-|----------|-------------|
-| `questionnaires` | Survey and questionnaire management system |
-| `kanban-todo` | Kanban-style todo list with drag-and-drop |
+| Option | Alias | Default | Description |
+|---|---|---|---|
+| `--template <name>` | `-t` | `typical` | Project template to use |
+| `--no-install` | | | Skip dependency installation |
+| `--use-npm` | | | Force npm as the package manager |
+| `--use-yarn` | | | Force yarn as the package manager |
+| `--use-pnpm` | | | Force pnpm as the package manager |
+| `--version` | `-V` | | Print version number |
+| `--help` | `-h` | | Show help |
 
-### Presets
+### Available templates
 
-| Preset | Description |
-|--------|-------------|
-| `minimal` | Narrative and server generator only |
-| `full` | All Auto Engineer packages |
+| Template | Description |
+|---|---|
+| `typical` | A handpicked set of builders curated by the Auto team (default) |
+| `minimal` | Minimal template with a single plugin for testing |
 
----
+Templates are discovered dynamically from the `templates/` directory via `template.json` metadata files.
 
-## Troubleshooting
+### Generated project structure
 
-### Directory Already Exists
+```
+my-app/
+├── .context/           # Design system context files
+├── narratives/         # Narrative-driven development files
+├── server/             # Server-side code
+├── auto.config.ts      # Auto Engineer pipeline configuration
+├── package.json
+├── pnpm-workspace.yaml
+└── .env.example
+```
 
-**Symptom:** Error about existing directory
+The generated `auto.config.ts` receives a unique `fileId` (via `@auto-engineer/id`) so each project is independently identifiable.
 
-**Cause:** Project directory already exists with files
+## Troubleshooting
 
-**Solution:**
+### Debug logging
 
-```bash
-# Overwrite existing directory
-create-auto-app my-app --force
-# Or choose a different name
-create-auto-app my-new-app
-```
+The CLI uses `ora` spinners and `chalk` colored output. Errors are printed to stderr with red highlighting. To see full stack traces, check the terminal output directly -- the CLI does not swallow errors silently.
 
-### Template Not Found
+### Directory already exists
 
-**Symptom:** Template not recognized
+**Symptom:** Prompted "Directory X already exists. Overwrite?"
 
-**Cause:** Invalid template name
+**Fix:** Confirm the overwrite prompt, or choose a different project name. There is no `--force` flag; the CLI always asks for confirmation before deleting an existing directory.
 
-**Solution:**
+### Template not found
 
-```bash
-# List available templates
-create-auto-app --help
-# Use valid template name
-create-auto-app my-app --template=kanban-todo
-```
+**Symptom:** `Template "foo" not found at ...`
 
-### Package Manager Not Found
+**Fix:** Run `create-auto-app --help` to see the template names listed in the `--template` option description. Use one of the listed names.
 
-**Symptom:** Installation fails
+### Package manager not found
 
-**Cause:** Specified package manager not installed
+**Symptom:** Dependency installation fails.
 
-**Solution:**
+**Fix:** Install the desired package manager globally, or use a different one:
 
 ```bash
-# Install pnpm
 npm install -g pnpm
-# Then create project
-create-auto-app my-app --use-pnpm
+npx create-auto-app my-app --use-pnpm
 ```
 
-### Enable Debug Logging
+### Dependencies fail to install
 
-```bash
-DEBUG=create-auto-app:* create-auto-app my-app
+**Symptom:** `Failed to install dependencies` message.
+
+**Fix:** The spinner will show the failure. Common causes:
+- Network issues reaching the npm registry.
+- Conflicting lockfiles. Delete `node_modules` and the lockfile, then run the install command manually.
+- Missing `pnpm-workspace.yaml`. The CLI creates one automatically if absent, but if something interrupts the process, create it manually:
+
+```yaml
+packages:
+  - '*'
 ```
 
----
+### Version resolution fails
+
+**Symptom:** `@auto-engineer/*` packages show as `latest` instead of a pinned version.
+
+**Cause:** `npm view <package> version` failed (network issue or package not yet published).
+
+**Fix:** After scaffolding, manually set the versions in `package.json` and re-run `pnpm install`.
 
 ## Architecture
 
+```mermaid
+graph TD
+    A[create-auto-app CLI] --> B[commander: parse args]
+    B --> C{project-name provided?}
+    C -->|No| D[inquirer: interactive prompts]
+    C -->|Yes| E[resolve options from flags]
+    D --> F[createProject]
+    E --> F
+    F --> G[prepareTargetDirectory]
+    G --> H[createFromTemplate]
+    H --> I[fs-extra: copy template files]
+    I --> J[collectAllAutoEngineerPackages]
+    J --> K[npm view: fetch latest versions]
+    K --> L[updatePackageVersions]
+    L --> M["replaceTemplateFileId (@auto-engineer/id)"]
+    M --> N{--no-install?}
+    N -->|No| O[execa: run package manager install]
+    N -->|Yes| P[print success message]
+    O --> P
+```
+
+### Source layout
+
 ```
 src/
-├── index.ts
-├── templates.ts
-├── project.ts
-└── utils.ts
+└── index.ts            # CLI entry point, all scaffolding logic
+scripts/
+└── copy-templates.ts   # Build script: copies examples/ into templates/
 templates/
-├── kanban-todo/
-└── questionnaires/
-```
-
-### Generated Project Structure
-
-```
-my-app/
-├── narratives/
-├── .context/
-├── server/
-├── client/
-├── auto.config.ts
-├── package.json
-├── pnpm-workspace.yaml
-└── .gitignore
+├── typical/            # Full-featured template
+└── minimal/            # Single-plugin template
 ```
 
 ### Dependencies
 
-| Package | Usage |
-|---------|-------|
-| `@auto-engineer/id` | Generate unique project IDs |
-| `commander` | CLI argument parsing |
-| `inquirer` | Interactive prompts |
-| `chalk` | Terminal styling |
-| `ora` | Loading spinners |
-| `execa` | Execute shell commands |
-| `fs-extra` | File system operations |
+| Package | Purpose |
+|---|---|
+| `@auto-engineer/id` | Generate unique 9-character fileId for each project |
+| `commander` | CLI argument parsing and help text |
+| `inquirer` | Interactive terminal prompts |
+| `chalk` | Colored terminal output |
+| `ora` | Loading spinners for async operations |
+| `execa` | Execute shell commands (package manager detection, installs, npm view) |
+| `fs-extra` | File system operations (copy, readJson, ensureDir) |
+| `@scarf/scarf` | Anonymous install analytics |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-auto-app",
-  "version": "1.148.0",
+  "version": "1.149.0",
   "description": "Create Auto Engineer apps with no configuration",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
     "fs-extra": "^11.2.0",
     "inquirer": "^9.2.15",
     "ora": "^8.0.1",
-    "@auto-engineer/id": "1.148.0"
+    "@auto-engineer/id": "1.149.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/minimal/README.md

@@ -1,116 +1,56 @@
-# Support Files
+# Support Files — Shared design system assets for Auto Engineer examples
 
-Shared design system assets for Auto Engineer examples.
+## Files
 
----
+| File | Description | Size |
+|------|-------------|------|
+| `.env.example` | Environment variable template for AI provider keys and configuration | ~500B |
+| `.context/design-system.md` | Component catalog listing 55+ shadcn/ui components by name and type | ~5KB |
+| `.context/figma-file.json` | Raw Figma API export with Tailwind CSS design tokens (spacing, dimensions, scopes) | ~44MB |
+| `.context/shadcn-filter.ts` | Filter function for processing Figma component imports (blacklist, dedup, kebab-case) | ~2KB |
 
-## Purpose
-
-This directory provides pre-configured design system files that other examples copy into their `.context/` directories. These files are consumed by the `@auto-engineer/generate-react-client` package and frontend generation plugins.
-
----
-
-## Directory Structure
-
-```
-support-files/
-├── .env.example          # Environment variable template
-└── .context/
-    ├── design-system.md    # Component documentation
-    ├── figma-file.json     # Figma design tokens (~44MB)
-    └── shadcn-filter.ts    # Component filtering logic
-```
-
----
-
-## File Descriptions
+## Usage
 
-### .env.example
+### Copying into a project
 
-Template for Auto Engineer environment variables:
+From another example directory, copy the context files:
 
 ```bash
-# AI Provider Keys
-ANTHROPIC_API_KEY=
-OPENAI_API_KEY=
-GEMINI_API_KEY=
-XAI_API_KEY=
-
-# Defaults
-DEFAULT_AI_PROVIDER=anthropic
-DEFAULT_AI_MODEL=vertex_ai/gemini-3.1-pro-preview
-
-# Debug
-DEBUG=auto:*
+rm -rf .context && mkdir .context && cp ../support-files/.context/* ./.context
 ```
 
-### .context/design-system.md
-
-Generated markdown listing 55+ shadcn/ui components:
-
-| Category | Components |
-|----------|------------|
-| Form | button, checkbox, input, select, switch, textarea, slider |
-| Layout | accordion, card, dialog, drawer, sheet, tabs, separator |
-| Navigation | breadcrumb, menubar, navigation-menu, pagination |
-| Data | avatar, badge, calendar, data-table, table |
-| Feedback | alert, alert-dialog, progress, skeleton, toast, tooltip |
-
-### .context/figma-file.json
-
-Raw Figma API export containing design tokens:
-
-- **Spacing**: `spacing/0`, `spacing/px`, `spacing/1`...`spacing/96`
-- **Dimensions**: `w-0`, `h-0`, `h-px`, `w-full`, `h-screen`
-- **Scopes**: GAP, WIDTH_HEIGHT configurations
-
-### .context/shadcn-filter.ts
-
-Filter function for processing Figma components during import:
-
-**Excludes:**
-- Generic names: `image`, `slot`, `logo`, `icon`
-- Internal components: `toolbar`, `stepper`, `sidebar`
-
-**Includes:**
-- Valid component names (1-3 words, alphabetic)
-- `INSTANCE` type components
-- Hierarchy depth ≤ 3
-
-**Transforms:**
-- Converts to lowercase kebab-case
-- Deduplicates and sorts
-
----
-
-## Usage
-
-### Copying to a Project
+### Environment setup
 
-From another example directory:
+Copy the env template and fill in your credentials:
 
 ```bash
-rm -rf .context && mkdir .context && cp ../support-files/.context/* ./.context
+cp ../support-files/.env.example ./.env
 ```
 
-The `kanban-todo` example includes this in its clean script:
+At minimum, set one AI provider key:
 
 ```bash
-pnpm clean  # Runs the copy automatically
+ANTHROPIC_API_KEY=your-key
+# or
+OPENAI_API_KEY=your-key
+# or
+GEMINI_API_KEY=your-key
+# or
+XAI_API_KEY=your-key
 ```
 
-### Using with Design System Importer
+Optional settings for custom OpenAI-compatible endpoints:
 
 ```bash
-auto import:design-system \
-  --output-dir=./.context \
-  --strategy=WITH_COMPONENT_SETS \
-  --filter-path=./shadcn-filter.ts
+CUSTOM_PROVIDER_NAME=litellm
+CUSTOM_PROVIDER_BASE_URL=https://api.litellm.ai
+CUSTOM_PROVIDER_API_KEY=your-custom-api-key
+CUSTOM_PROVIDER_DEFAULT_MODEL=vertex_ai/gemini-3.1-pro-preview
 ```
 
-### Pipeline Integration
+### Pipeline integration
 
-In `auto.config.ts`, reference these files:
+Reference these files in `auto.config.ts`:
 
 ```typescript
 .on('IAGenerated')
@@ -123,25 +63,21 @@ In `auto.config.ts`, reference these files:
 }))
 ```
 
----
+### Regenerating from Figma
 
-## Regenerating Files
-
-To regenerate from a Figma source:
+To regenerate the design system files from a Figma source:
 
 ```bash
-# Set credentials
 export FIGMA_PERSONAL_TOKEN=your-token
 export FIGMA_FILE_ID=your-file-id
 
-# Run importer
 auto import:design-system \
   --output-dir=./.context \
-  --strategy=WITH_ALL_FIGMA_INSTANCES \
+  --strategy=WITH_COMPONENT_SETS \
   --filter-path=./shadcn-filter.ts
 ```
 
-**Import Strategies:**
+Import strategies:
 
 | Strategy | Description |
 |----------|-------------|
@@ -149,11 +85,31 @@ auto import:design-system \
 | `WITH_COMPONENT_SETS` | Component sets (default) |
 | `WITH_ALL_FIGMA_INSTANCES` | Full document traversal |
 
----
+## API Reference
+
+### `shadcn-filter.ts`
+
+```typescript
+export function filter(components: Component[]): Component[]
+```
+
+Filters and transforms a list of Figma components for import into the design system.
+
+**Filtering rules:**
+
+- Excludes names matching a blacklist: `image`, `slot`, `logo`, `sidebar`, `settings`, `stepper`, and others
+- Excludes names containing substrings: `icon`, `diagram`, `toolbar`, `shortcut`, `script`
+- Includes only components where the name is 1-3 alphabetic words, description is `INSTANCE`, and hierarchy depth is 3 or less
+- Deduplicates by lowercase name
+
+**Transforms:**
+
+- Converts names to lowercase kebab-case
+- Sorts alphabetically
 
-## Related Packages
+### Consumed by
 
-| Package | Relationship |
-|---------|--------------|
-| `@auto-engineer/generate-react-client` | Uses design system files for client generation |
-| `@auto-engineer/information-architect` | References component list for IA |
+| Package | How it uses these files |
+|---------|----------------------|
+| `@auto-engineer/react-gen` | Reads `design-system.md` and `figma-file.json` during client generation |
+| `@auto-engineer/information-architect` | References the component list for information architecture decisions |

package/templates/typical/README.md

@@ -1,116 +1,56 @@
-# Support Files
+# Support Files — Shared design system assets for Auto Engineer examples
 
-Shared design system assets for Auto Engineer examples.
+## Files
 
----
+| File | Description | Size |
+|------|-------------|------|
+| `.env.example` | Environment variable template for AI provider keys and configuration | ~500B |
+| `.context/design-system.md` | Component catalog listing 55+ shadcn/ui components by name and type | ~5KB |
+| `.context/figma-file.json` | Raw Figma API export with Tailwind CSS design tokens (spacing, dimensions, scopes) | ~44MB |
+| `.context/shadcn-filter.ts` | Filter function for processing Figma component imports (blacklist, dedup, kebab-case) | ~2KB |
 
-## Purpose
-
-This directory provides pre-configured design system files that other examples copy into their `.context/` directories. These files are consumed by the `@auto-engineer/generate-react-client` package and frontend generation plugins.
-
----
-
-## Directory Structure
-
-```
-support-files/
-├── .env.example          # Environment variable template
-└── .context/
-    ├── design-system.md    # Component documentation
-    ├── figma-file.json     # Figma design tokens (~44MB)
-    └── shadcn-filter.ts    # Component filtering logic
-```
-
----
-
-## File Descriptions
+## Usage
 
-### .env.example
+### Copying into a project
 
-Template for Auto Engineer environment variables:
+From another example directory, copy the context files:
 
 ```bash
-# AI Provider Keys
-ANTHROPIC_API_KEY=
-OPENAI_API_KEY=
-GEMINI_API_KEY=
-XAI_API_KEY=
-
-# Defaults
-DEFAULT_AI_PROVIDER=anthropic
-DEFAULT_AI_MODEL=vertex_ai/gemini-3.1-pro-preview
-
-# Debug
-DEBUG=auto:*
+rm -rf .context && mkdir .context && cp ../support-files/.context/* ./.context
 ```
 
-### .context/design-system.md
-
-Generated markdown listing 55+ shadcn/ui components:
-
-| Category | Components |
-|----------|------------|
-| Form | button, checkbox, input, select, switch, textarea, slider |
-| Layout | accordion, card, dialog, drawer, sheet, tabs, separator |
-| Navigation | breadcrumb, menubar, navigation-menu, pagination |
-| Data | avatar, badge, calendar, data-table, table |
-| Feedback | alert, alert-dialog, progress, skeleton, toast, tooltip |
-
-### .context/figma-file.json
-
-Raw Figma API export containing design tokens:
-
-- **Spacing**: `spacing/0`, `spacing/px`, `spacing/1`...`spacing/96`
-- **Dimensions**: `w-0`, `h-0`, `h-px`, `w-full`, `h-screen`
-- **Scopes**: GAP, WIDTH_HEIGHT configurations
-
-### .context/shadcn-filter.ts
-
-Filter function for processing Figma components during import:
-
-**Excludes:**
-- Generic names: `image`, `slot`, `logo`, `icon`
-- Internal components: `toolbar`, `stepper`, `sidebar`
-
-**Includes:**
-- Valid component names (1-3 words, alphabetic)
-- `INSTANCE` type components
-- Hierarchy depth ≤ 3
-
-**Transforms:**
-- Converts to lowercase kebab-case
-- Deduplicates and sorts
-
----
-
-## Usage
-
-### Copying to a Project
+### Environment setup
 
-From another example directory:
+Copy the env template and fill in your credentials:
 
 ```bash
-rm -rf .context && mkdir .context && cp ../support-files/.context/* ./.context
+cp ../support-files/.env.example ./.env
 ```
 
-The `kanban-todo` example includes this in its clean script:
+At minimum, set one AI provider key:
 
 ```bash
-pnpm clean  # Runs the copy automatically
+ANTHROPIC_API_KEY=your-key
+# or
+OPENAI_API_KEY=your-key
+# or
+GEMINI_API_KEY=your-key
+# or
+XAI_API_KEY=your-key
 ```
 
-### Using with Design System Importer
+Optional settings for custom OpenAI-compatible endpoints:
 
 ```bash
-auto import:design-system \
-  --output-dir=./.context \
-  --strategy=WITH_COMPONENT_SETS \
-  --filter-path=./shadcn-filter.ts
+CUSTOM_PROVIDER_NAME=litellm
+CUSTOM_PROVIDER_BASE_URL=https://api.litellm.ai
+CUSTOM_PROVIDER_API_KEY=your-custom-api-key
+CUSTOM_PROVIDER_DEFAULT_MODEL=vertex_ai/gemini-3.1-pro-preview
 ```
 
-### Pipeline Integration
+### Pipeline integration
 
-In `auto.config.ts`, reference these files:
+Reference these files in `auto.config.ts`:
 
 ```typescript
 .on('IAGenerated')
@@ -123,25 +63,21 @@ In `auto.config.ts`, reference these files:
 }))
 ```
 
----
+### Regenerating from Figma
 
-## Regenerating Files
-
-To regenerate from a Figma source:
+To regenerate the design system files from a Figma source:
 
 ```bash
-# Set credentials
 export FIGMA_PERSONAL_TOKEN=your-token
 export FIGMA_FILE_ID=your-file-id
 
-# Run importer
 auto import:design-system \
   --output-dir=./.context \
-  --strategy=WITH_ALL_FIGMA_INSTANCES \
+  --strategy=WITH_COMPONENT_SETS \
   --filter-path=./shadcn-filter.ts
 ```
 
-**Import Strategies:**
+Import strategies:
 
 | Strategy | Description |
 |----------|-------------|
@@ -149,11 +85,31 @@ auto import:design-system \
 | `WITH_COMPONENT_SETS` | Component sets (default) |
 | `WITH_ALL_FIGMA_INSTANCES` | Full document traversal |
 
----
+## API Reference
+
+### `shadcn-filter.ts`
+
+```typescript
+export function filter(components: Component[]): Component[]
+```
+
+Filters and transforms a list of Figma components for import into the design system.
+
+**Filtering rules:**
+
+- Excludes names matching a blacklist: `image`, `slot`, `logo`, `sidebar`, `settings`, `stepper`, and others
+- Excludes names containing substrings: `icon`, `diagram`, `toolbar`, `shortcut`, `script`
+- Includes only components where the name is 1-3 alphabetic words, description is `INSTANCE`, and hierarchy depth is 3 or less
+- Deduplicates by lowercase name
+
+**Transforms:**
+
+- Converts names to lowercase kebab-case
+- Sorts alphabetically
 
-## Related Packages
+### Consumed by
 
-| Package | Relationship |
-|---------|--------------|
-| `@auto-engineer/generate-react-client` | Uses design system files for client generation |
-| `@auto-engineer/information-architect` | References component list for IA |
+| Package | How it uses these files |
+|---------|----------------------|
+| `@auto-engineer/react-gen` | Reads `design-system.md` and `figma-file.json` during client generation |
+| `@auto-engineer/information-architect` | References the component list for information architecture decisions |