@mars-stack/cli 0.2.0

package/README.md

@@ -0,0 +1,140 @@
+# @mars-stack/cli
+
+CLI for scaffolding and managing MARS projects. Designed to be used by AI agents (via skills) or directly by developers.
+
+## Install
+
+```bash
+# Use without installing (recommended)
+npx @mars-stack/cli create my-app
+
+# Or install globally
+npm i -g @mars-stack/cli
+mars create my-app
+```
+
+## Commands
+
+### `mars create [name]`
+
+Scaffold a new project. Walks through four interactive prompt groups:
+
+1. **Project info** -- name (kebab-case), display name, description, URL, support email
+2. **Features** -- toggle 24 features across auth, app, infrastructure, and architecture categories
+3. **Services** -- pick providers for database, email, storage, payments, analytics, search, realtime, and background jobs
+4. **Theme** -- brand colour, font family, design direction
+
+Outputs a complete Next.js application with auth, design tokens, database schema, agent infrastructure (AGENTS.md, skills, rules, docs), and a working dev environment.
+
+```bash
+mars create my-app
+# → interactive prompts
+# → scaffolds ~200 files
+# → prints next steps
+```
+
+### `mars add feature <name>`
+
+Generate a feature module at `src/features/<name>/` with:
+- `server/index.ts` -- typed CRUD operations with `import 'server-only'`
+- `types.ts` -- Zod validation schemas and TypeScript types
+
+```bash
+mars add feature billing
+# → src/features/billing/server/index.ts
+# → src/features/billing/types.ts
+```
+
+### `mars add page <path> [--protected]`
+
+Create a page component with a loading skeleton.
+
+```bash
+mars add page pricing                    # → src/app/pricing/page.tsx
+mars add page dashboard/analytics -p     # → src/app/(protected)/dashboard/analytics/page.tsx
+mars add page blog/[slug]                # → src/app/blog/[slug]/page.tsx
+```
+
+### `mars add model <name>`
+
+Create a Prisma schema file with a starter model, timestamps, and user relation.
+
+```bash
+mars add model Product
+# → prisma/schema/product.prisma (with Product model)
+```
+
+### `mars add component <name> [--type primitive|pattern]`
+
+Create a UI component in the correct directory.
+
+```bash
+mars add component Toggle                # → src/components/primitives/Toggle.tsx
+mars add component DataGrid --type pattern   # → src/components/patterns/DataGrid.tsx
+```
+
+### `mars add email <name>`
+
+Create a React Email template with the base layout, inline styles, and email-client-safe markup.
+
+```bash
+mars add email team-invite
+# → src/lib/core/email/templates/team-invite-email.ts
+```
+
+### `mars configure [service]`
+
+Configure a service provider. Installs the SDK, updates `app.config.ts`, and writes env vars to `.env`.
+
+```bash
+mars configure payments   # → installs stripe, updates config, adds env vars
+mars configure email      # → prompts for SendGrid or Resend, installs SDK
+mars configure storage    # → prompts for Vercel Blob, S3, or local
+```
+
+### `mars deploy`
+
+Guided Vercel deployment:
+
+1. Checks `vercel` CLI is installed
+2. Links the project to your Vercel account
+3. Detects configured services from `app.config.ts`
+4. Prompts for and sets each required env var
+5. Runs the deployment
+6. Prints the deployed URL
+
+### `mars doctor [--upgrade-check]`
+
+Check your development environment: Node version, package manager, dependencies, database connection, required env vars.
+
+```bash
+mars doctor                 # basic health check
+mars doctor --upgrade-check # also check for Mars package updates
+```
+
+### `mars upgrade`
+
+Update `@mars-stack/core` and `@mars-stack/ui` to latest, run install, verify with `mars doctor`.
+
+```bash
+mars upgrade           # upgrade to latest
+mars upgrade --dry-run # preview what would change
+```
+
+### `mars telemetry <enable|disable>`
+
+Opt in or out of anonymous usage analytics. Stored in `~/.marsrc`. Tracks command usage and feature selections only -- never project names, file contents, or env vars.
+
+## Agent Usage
+
+The CLI is designed to be invoked by AI agents following Mars skills. The agent reads the skill, determines which CLI commands to run, and executes them. For example:
+
+- The `build-complete-feature` meta-skill chains `mars add model`, `mars add feature`, and `mars add page`
+- The `setup-billing` meta-skill runs `mars configure payments` then builds the billing UI
+- The `deploy-to-vercel` skill runs `mars deploy` with guided prompts
+
+Skills live in `.cursor/skills/` (installed automatically via `@mars-stack/core` postinstall).
+
+## License
+
+MIT